OpenGLEAN
OpenGLEAN User Support
Home page | Introduction | Documentation | Files | Examples | Proposals | Authors | Links


OpenGLEAN Device Support Development
Summary | CVS | (discussion via home page) | (contact via home page) | (suggestion box) | License | Todo | Bugs

Rename the API

NB: As of this writing, OpenGLEAN installs its man pages into the UNIX man section 3f. I plan to make this configurable. This proposal will probably be discarded.

Introduction

This proposal is just a random thought for public consumption. freeglut forked the GLUT API and after 5 years of work is still incomplete. OpenGLUT forked the freeglut codebase and provided new man-pages. (freeglut never had any man-pages, relying on the old GLUT man-pages instead.) It turns out that the old GLUT API also had man-pages, though they were never widely distributed.

Now, OpenGLEAN has forked OpenGLUT, and the OpenGLUT man-pages.

The Problem:

Unfortunately, you start to run into collisions if you try to install man-pages for GLUT, OpenGLUT, and OpenGLEAN. Whose glutCreateWindow.[03] do you install? Right now, the answer may seem pretty straightforward: OpenGLUT and OpenGLEAN both normally install man-pages, GLUT man-pages are rare. OpenGLUT and OpenGLEAN provide almost identical man-pages that are fairly complete and which address features not found in old GLUT. So, install either OpenGLUT or OpenGLEAN man pages and forget it, right?

The problem is that OpenGLEAN has already removed one obsolete function and will remove many others. And, of course, one of the reasons for stripping deadwood from OpenGLEAN is to make the library more nimble. It is expected that the documentation for both libraries will eventually include references to things that don't exist in the other without documenting the portability issue.

Another problem is that OpenGLUT tries to force its own man-page installation, and OpenGLEAN presently inherits this---and both install to the autoconf ${PREFIX} path, in section "3". So you will get conflicts if you try to install both libraries.

The Advantage As It Is:

Currently, old programs just work. Skills and knowledge can go back and forth.

Workarounds

There are some workarounds that you can employ, such as using the 3f man-page section, or presuming that one set is in the base-system while another is added only as a package, with a wholly separate directory tree. OpenGLEAN may provide a way for you to specify a non-default library section for OpenGLEAN documentation or to disable man-pages altogether.

Renaming

Renaming the API is relatively easy. Just change all "glut" symbol prefixes to "glean" (and "GLUT" to "GLEAN"). Done. (Warning: It turns out that there is a project called glean that has nothing to do with OpenGLEAN. However, that project appears to be dead, and I'm not really going to rename OpenGLEAN yet again, after producing the OpenGLUT fork and OpenGLEAN. Renaming a project is more work than just renaming the API! Enough is enough.)

Coping With the Fallout

If OpenGLEAN's API is renamed to avoid clashing with GLUT/freeglut/OpenGLUT, some optional #define symbols can be added, so that porting between GLUT, freeglut, OpenGLUT, and OpenGLEAN can still be done with a few tweaks to the compilation command-line.

Conclusion

I'm not terribly happy with this idea at present, but it's something that I wanted to put down in writing for reflection. At least for now, OpenGLEAN will retain the GLUT API, broadly. Maybe when I chop out some of the more core old features (the old font API and the old menu API), that will be a time to begin the transition. Those changes are coming, but not immediately.



SourceForge.net Logo Supported in part by SourceForge.net.

Generated on Fri Sep 9 18:01:32 2005 for gleandev by doxygen 1.4.3
The OpenGLEAN project is hosted in part by SourceForge.