Adding the Cygwin/mingw documentation from Jean-Seb (see e-mail dated Thu 7/9/2009 5:51 PM)

git-svn-id: https://svn.code.sf.net/p/freeglut/code/trunk@829 7f0cb862-5218-0410-a997-914c9d46530a

.gitattributes

@@ -3,11 +3,13 @@ freeglut/freeglut/AUTHORS svn_keywords=Author+Date+Id+Revision
 freeglut/freeglut/COPYING svn_keywords=Author+Date+Id+Revision
 freeglut/freeglut/ChangeLog svn_keywords=Author+Date+Id+Revision
 freeglut/freeglut/FrequentlyAskedQuestions -text
+freeglut/freeglut/LISEZMOI.cygwin_mingw -text
 freeglut/freeglut/LISEZ_MOI svn_keywords=Author+Date+Id+Revision
 freeglut/freeglut/Makefile.am svn_keywords=Author+Date+Id+Revision
 freeglut/freeglut/Makefile.wat -text
 freeglut/freeglut/NEWS svn_keywords=Author+Date+Id+Revision
 freeglut/freeglut/README svn_keywords=Author+Date+Id+Revision
+freeglut/freeglut/README.cygwin_mingw -text
 freeglut/freeglut/README.win32 svn_keywords=Author+Date+Id+Revision
 freeglut/freeglut/TODO svn_keywords=Author+Date+Id+Revision
 freeglut/freeglut/VisualStudio2008/CallbackMaker/CallbackMaker.vcproj -text

freeglut/freeglut/LISEZMOI.cygwin_mingw

@@ -0,0 +1,218 @@
+Glut alors!
+
+Par Jean-Seb le vendredi 10 juillet 2009, 00:18
+
+
+Freeglut est une évolution open-source de Glut.
+Sous Windows, on peut l'utiliser avec Cygwin.
+Facile ? Oui, si on accepte de distribuer "cygwin1.dll"
+Aidons Freeglut à conquérir son indépendance !
+m.à.j 10/7/2009 : génération d'une librairie pour linker depuis la dll.
+
+
+Récupération des sources
+
+    * Reprenez les sources de la version 2.6.0 qui intègre les changements
+      récents.
+    * Pour l'instant, il s'agit d'une RC (Release Candidate), mais la version
+      finale ne saurait tarder.
+    * L'utilisation de la 2.6 est préférable à la branche 2.4-stable, de
+      nombreux bugs étant corrigés.
+    * Vous trouverez les sources sur le site de Freeglut:
+          o http://freeglut.sourceforge.net/
+
+
+Principe
+Objectif
+
+    * Nous allons créer une dll liée à Cygwin, et une bibliothèque statique
+      indépendante
+    * Nous créerons également une librairie dynamique, permettant de linker avec
+      la dll.
+
+Liste des fichiers générés
+
+    * freeglut.dll : une dll classique pour le linkage dynamique.
+    * libfreeglut.a : la bibliothèque statique. Le programme final est autonome
+      (du moins pour OpenGL).
+    * libfreeglutdll.a : la bibliothèque dynamique. Le programme final a besoin
+      de freeglut.dll.
+
+
+Préparation
+
+    * Dépliez l'archive freeglut.
+    * Allez dans le répertoire src (situé à la racine du répertoire Freeglut),
+      et créez un sous-répertoire "Gl"
+          o Dans ce sous-répertoire, copiez les fichiers du répertoire
+            "include/Gl"
+
+    * Pourquoi faut-il créer un répertoire "Gl" pour la compilation ?
+          o C'était juste pour simplifier les choses lors de mes essais.
+          o Sinon vous pouvez créer directement les répertoires, et copier les
+            fichiers comme indiqué au point installation (lire plus loin).
+
+    * Faites un peu de ménage dans /lib :
+          o Effacez toutes les références à la glut, pour ne pas avoir de
+            conflit au linkage.
+          o Cette étape est facultative, vous pouvez également choisir de ne
+            faire le ménage qu' après une compilation réussie de Freeglut.
+          o Attention à ne pas effacer, dans un enthousiasme rédempteur, la
+            bibliothèque glu32.lib (à ne pas confondre avec glut32.lib).
+
+
+Compilation
+
+    * Oubliez le triptyque ./configure , make , make install.
+          o Ca ne marche pas du tout avec Cygwin.
+
+    * Voici un Makefile qui fera l'affaire:
+
+#Makefile pour Freeglut 2.6.0-rc et Cygwin
+#A placer dans le répertoire "src"
+
+sources=$(wildcard *.c)
+objs=$(sources:.c=.o)
+libname=freeglut
+
+
+CFLAGS=-O2 -DTARGET_HOST_MS_WINDOWS -DX_DISPLAY_MISSING -DFREEGLUT_STATIC -I./
+LDFLAGS=-lopengl32 -lgdi32 -lwinmm
+
+nocyg=-mno-cygwin -mwindows
+
+all: $(objs)
+        #construction dll liée à cygwin1.dll
+        gcc $(nocyg) $(objs) -shared $(LDFLAGS) -o $(libname).dll
+        nm $(libname).dll  | awk 'BEGIN { print "EXPORTS" } /T _glut/ {sub( /^.*T _/, "\t"); print}' > $(libname).def
+        dlltool --dllname $(libname).dll --input-def $(libname).def --output-lib lib$(libname)dll.a
+
+        #construction bibliothèque statique indépendante de cygwin
+        ar cr lib$(libname).a $(objs)
+        #pas forcément obligatoire (création d'un index pour accélérer les accès)
+        ranlib lib$(libname).a
+
+%.o: %.c
+        gcc $(nocyg) -c $(CFLAGS) $<
+
+clean:
+        rm -f *.o $(libname).dll $(libname).def lib$(libname)dll.a lib$(libname).a
+
+
+
+
+Quelques remarques sur le makefile
+
+    * Ce makefile crée une dll, une bibliothèque statique (une archive, en
+      d'autres termes) et la bibliothèque dynamique qui permettra l'utilisation
+      de la dll.
+
+    * Ne cherchez pas à stripper la bibliothèque statique! Vous ne pourriez plus
+      compiler en statique.
+          o Par contre, vous pouvez stripper l'exécutable final obtenu lors de
+            la compilation de votre application.
+
+    * J'ai choisi d'appeller la dll et les bibliothèques par leurs "vrais noms":
+      freeglut.dll libfreeglutdll.a et libfreeglut.a.
+          o Le script configure recréait (pour des raisons de compatibilité avec
+            l'ancienne bibliothèque Glut) glut.dll et libglut.a.
+          o Lors des mes essais, j'ai eu des conflits avec une authentique
+            "glut" qui trainait dans mon "/lib". J'ai décidé d'appeller les
+            choses par leur nom, afin d'éviter les confusions.
+          o Rien ne vous empêche de renommer la dll, si vous avez besoin
+            d'utiliser des programmes Glut que vous ne pouvez pas recompiler.
+
+    * La bibliothèque dynamique est générée à partir de la dll.
+          o Par souci de concision, j'ai utilisé awk. Il génère le fichier
+            d'exports utilisé par dlltool.
+          o La seule chose notable est la sélection des fonctions dont le nom
+            commence par _glut, afin d'éviter d'inclure dans la librairie
+            dynamique des fonctions sans rapport avec freeglut.
+          o ensuite, on utilise dlltool de façon très classique.
+
+nm $(libname).dll  | awk 'BEGIN { print "EXPORTS" } /T _glut/ {sub( /^.*T _/, "\t"); print}' > $(libname).def
+dlltool --dllname $(libname).dll --input-def $(libname).def --output-lib lib$(libname)dll.a
+
+
+
+
+Installation
+
+    * Copiez libfreeglut.a, libfreeglutdll.a dans le répertoire /lib de Cygwin.
+    * Copiez freglut.dll dans le system32 de Windows (ce qui est pratique, mais
+      pas propre!).
+    * Copiez les fichiers headers de Freeglut (/include/gl) dans /usr/include/Gl
+      de Cygwin.
+    * Copiez les fichiers headers (toujours /include/gl) dans
+      /usr/include/mingw/Gl : ceci sert aux compilations avec le flag
+      -mno-cygwin, qui utilise alors les includes de mingw.
+          o Vous aurez éventuellement besoin d'écraser d'anciens fichiers
+            include, correspondants à Glut, si vous l'avez installé avec Cygwin.
+
+
+Utilisation de la librairie
+
+    * Nous allons tester avec le programme shapes, présent dans
+      progs/demos/shapes
+          o -mno-cygwin sert à forcer l'utilisation de Mingw sans la grosse
+            dépendance cygwin1.dll.
+          o -mwindows sert uniquement à enlever l'horrible fenêtre shell (très
+            utile pour la mise au point, par contre).
+          o -L. (notez le point après le "L") : j'ai laissé libfreeglut.a,
+            libfreeglutdll.a et freeglut.dll dans le répertoire de test, le
+            temps des tests justement.
+
+
+Compilation en librairie statique freeglut, sans cygwin
+
+    * Toute l'astuce réside dans le define : -DFREEGLUT_STATIC
+          o Il sert à obtenir la bonne décoration des noms de fonctions dans les 
+            imports de la lib Freeglut.
+          o Vous pouvez essayer sans et prendre un éditeur hexa pour voir les
+            différences dans l'objet.
+    * attention à l'ordre des bibliothèques : -lfreeglut (statique) doit se
+      trouver avant la déclaration des bibliothèques dynamiques.
+
+    * gcc shapes.c -L. -lfreeglut -lopengl32 -lwinmm -lgdi32 -mno-cygwin
+      -mwindows -DFREEGLUT_STATIC
+
+
+Compilation avec dll freeglut, sans cygwin
+
+    * Pour le define, même remarque que ci-dessus
+    * L'ordre des bibliothèques n'a plus d'importance.
+
+    * gcc shapes.c -L. -lopengl32 -lwinmm -lgdi32 -lfreeglut -mno-cygwin
+      -DFREEGLUT_STATIC
+
+
+Compilation avec dll freeglut, avec Cygwin
+
+    * Cet exemple est donné uniquement pour référence, le thème de ce billet étant de se débarrasser de Cygwin.
+          o Disons que ça peut servir pendant la mise au point (et encore).
+
+    * gcc shapes.c -L. -lopengl32 -lwinmm -lgdi32 -lfreeglut
+
+
+
+Où sont les dooooocs ?
+
+    * Freeglut est livré avec sa documentation, plus très à jour.
+          o Il semble qu'il y ait un problème avec la doc Glut originale. Non
+            seulement elle ne correspond pas forcément au fonctionnement de
+            Freeglut, mais de plus, son auteur (Mark Kilgard) l'a copyrighté. Sa
+            distribution est donc difficile.
+
+    * Jocelyn Fréchot a entrepris une mise à niveau des docs pour la version
+      2.6.0. On peut les trouver sur son site pour l'instant:
+          o http://jocelyn.frechot.free.fr/freeglut/
+
+
+Quelque chose a survécu ...
+
+    * J'ai également testé la recompilation des démos de la lib Glut originelle
+      (paix à ses cendres).
+          o Rien de particulier à signaler.
+
+    * Merci à tous les mainteneurs courageux de Freeglut, qu'on croyait mort,
+      mais qui bouge encore.

freeglut/freeglut/README.cygwin_mingw

@@ -0,0 +1,212 @@
+Glut then!
+
+By Jean-Seb on Friday July 10, 2009, 00:18
+Translated by Babelfish with a scrub from John F. Fay.  For points of confusion
+please refer to the original French version.
+
+Freeglut is an open-source evolution of GLUT.
+Under Windows, one can use it with Cygwin.
+Easy? Yes, if one agrees to distribute "cygwin1.dll".
+Let us help freeglut gain its independence !
+m.à.j 10/7/2009: generation of a library for linking without the DLL.
+
+
+Recovery of the sources
+
+    * Download the sources of version 2.6.0 which integrates recent changes.
+    * For the moment, it is a RC (Release Candidate), but the final version
+      should not delay.
+    * The use of the 2.6 is preferable with the 2.4-stable branch because many
+      bugs have been corrected.
+    * You will find the sources on the site of Freeglut:
+          o http://freeglut.sourceforge.net/
+
+
+Objectives and preparation
+Objectives
+
+    * We will create a DLL related to Cygwin, and an independent static library
+    * We will also create a dynamic library, allowing linking with the DLL.
+
+
+List of generated files
+
+    * freeglut.dll: a traditional DLL for the dynamic linkage.
+    * libfreeglut.a: the static library. The final program is autonomous (at
+      least for OpenGL).
+    * libfreeglutdll.a: the dynamic library. The final program needs
+      freeglut.dll.
+
+
+Preparation
+
+    * Extract the files from the freeglut archive.
+    * Go in the directory src (located at the root of the Freeglut directory),
+      and create a "Gl" sub-directory
+          o In this sub-directory, copy the files of the directory "include/Gl"
+
+    * Why is it necessary to create a "Gl" directory for compilation?
+          o I needed it to simplify things during my tests.
+          o If not you can create the repertories directly, and copy the files
+            as indicated in the point installation (see below).
+
+    * Do a little housekeeping in /lib:
+          o Erase all the references to the glut, so as not to conflict with the
+            linking.
+          o This stage is optional, you can also choose to do the housekeeping
+            only after a successful compilation of Freeglut.
+          o In your enthusiasm to clean things up, be careful not to erase the
+            library glu32.lib (not to be confused with glut32.lib).
+
+
+Compilation
+
+    * Forget the "./configure, make, make install" triptych.
+          o It does not go at all with Cygwin.
+
+    * Here Makefile which will make the deal:
+
+#Makefile for Freeglut 2.6.0-rc and Cygwin
+#To place in the directory “src”
+
+sources=$ (wildcard *.c)
+objs=$ (sources: .c=.o)
+libname=freeglut
+
+
+CFLAGS=-O2 - DTARGET_HOST_MS_WINDOWS - DX_DISPLAY_MISSING - DFREEGLUT_STATIC - I./
+LDFLAGS=-lopengl32 - lgdi32 - lwinmm
+
+nocyg=-mno-cygwin - mwindows
+
+all: $ (objs)
+        #construction DLL related to cygwin1.dll
+        GCC $ (nocyg) $ (objs) - shared $ (LDFLAGS) - O $ (libname) .dll
+        Nm $ (libname) .dll  | awk “BEGIN {print “EXPORTS”} /T _glut/{sub (/^.*T _/,” \ T "); print}” > $ (libname) .def
+        dlltool --dllname $ (libname) .dll --input-def $ (libname) .def --output-lib lib$ (libname) dll.a
+
+        #construction static library independent of cygwin
+        rear Cr lib$ (libname) .a $ (objs)
+        #pas inevitably obligatory (creation of an index to accelerate the accesses)
+        ranlib lib$ (libname) .a
+
+%.o: %.c
+        GCC $ (nocyg) - C $ (CFLAGS) $<
+
+clean:
+        rm - F *.o $ (libname) .dll $ (libname) .def lib$ (libname) dll.a lib$ (libname) .a
+
+
+
+
+Some remarks on the makefile
+
+    * This makefile creates a DLL, a static library (a file, in other words) and
+      the dynamic library which will allow the use of the DLL.
+
+    * Do not try to strip the static library! You may not be able to compile
+      applications with static library any more.
+          o On the other hand, you can strip the final executable obtained after
+            compiling your application.
+
+    * I chose to call the DLL and the libraries by their "true names":
+      freeglut.dll libfreeglutdll.a and libfreeglut.a.
+          o Script configures recreated (for reasons of compatibility with the
+            old GLUT library) glut.dll and libglut.a.
+          o During the my tests, I had conflicts with an authentic "glut" which
+            trailed in my "/lib". I decided to call the things by their name, in
+            order to avoid confusions.
+          o Nothing prevents you from renaming the DLL, if you need to use GLUT
+            programs which you cannot recompile.
+
+    * The dynamic library is generated starting from the DLL.
+          o For reasons of brevity, I used awk. It generates the export file
+            used by dlltool.
+          o The only notable thing is the selection of the functions whose name
+            starts with _glut, in order to avoid including in the dynamic
+            library the functions that are not related to freeglut.
+          o then, one uses dlltool in a very traditional way.
+
+Nm $ (libname) .dll  | awk “BEGIN {print “EXPORTS”} /T _glut/{sub (/^.*T _/,” \ T "); print}” > $ (libname) .def
+dlltool --dllname $ (libname) .dll --input-def $ (libname) .def --output-lib lib$ (libname) dll.a
+
+
+
+
+Installation
+
+    * Copy libfreeglut.a, libfreeglutdll.a into the Cygwin directory /lib.
+    * Copy freglut.dll in the system32 of Windows (this is practical, but not
+      clean!).
+    * Copy the files headers of Freeglut (/include/gl) into the Cygwin directory
+      /usr/include/Gl.
+    * Copy the files headers (always /include/gl) into /usr/include/mingw/Gl:
+      this is used for compilations with the flag - mno-cygwin, which uses the
+      includes in mingw.
+          o You may need to erase the old GLUT include files if you installed it
+            with Cygwin.
+
+
+Use of the library
+
+    * We will test with the program shapes, found in progs/demonstrations/shapes
+          o -mno-cygwin is used to force the use of Mingw without the large
+            dependence cygwin1.dll.
+          o -mwindows is only used to remove the horrible Shell window (very
+            useful for the settling, on the other hand).
+          o -L. (note the period after the "L"): I left libfreeglut.a,
+            libfreeglutdll.a and freeglut.dll in the test directory, at the time 
+            of the tests.
+
+
+Compilation of the static freeglut library, without cygwin
+
+    * All the simplicity lies in the define: -DFREEGLUT_STATIC
+          o It serves to obtain good decoration of the function names in the
+            imports of the lib Freeglut.
+          o You can test without and use a hex editor to see the differences
+            in the objects.
+    * attention with the order of the libraries: -lfreeglut (static) must be
+      before the declaration of the dynamic libraries.
+
+    * gcc shapes.c -L. -lfreeglut -lopengl32 -lwinmm -lgdi32 -mno-cygwin -mwindows -DFREEGLUT_STATIC
+
+
+Compilation with DLL freeglut, without cygwin
+
+    * For the define, see the notices above
+    * The order of the libraries is no longer important.
+
+    * gcc shapes.c -L. -lopengl32 -lwinmm -lgdi32 -lfreeglut -mno-cygwin -DFREEGLUT_STATIC
+
+
+Compilation with DLL freeglut, Cygwin
+
+    * This example is given only for reference, the topic of this ticket being
+      to get rid of Cygwin.
+          o Let us say that can be used to make the point (and later).
+
+    * gcc shapes.c -L. -lopengl32 -lwinmm -lgdi32 -lfreeglut
+
+
+
+Where are the dooooocs?
+
+    * Freeglut is delivered with its documentation, more very up to date.
+          o It seems that there is a problem with the original GLUT
+            documentation. Not only it does not correspond completely to the
+            operation of Freeglut, but moreover, its author (Mark Kilgard)
+            copyrighted it. Its distribution is thus difficult.
+
+    * Jocelyn Fréchot undertook a levelling of the docs for version 2.6.0. One can find them on his site for the moment:
+          o http://jocelyn.frechot.free.fr/freeglut/
+
+
+Something survived…
+
+    * I also tested the recompiling of the demonstrations of the original lib
+      GLUT (peace with its ashes).
+          o Nothing in particular to be announced.
+
+    * Thank you with all the courageous maintainers for Freeglut, that one
+      believed dead, but which still move.