Added a few more details to README.cmake
[freeglut] / README.cygwin_mingw
1 Glut then!
2
3 By Jean-Seb on Friday July 10, 2009, 00:18
4 Translated by Babelfish with a scrub from John F. Fay.  For points of confusion
5 please refer to the original French version.
6
7 Freeglut is an open-source evolution of GLUT.
8 Under Windows, one can use it with Cygwin.
9 Easy? Yes, if one agrees to distribute "cygwin1.dll".
10 Let us help freeglut gain its independence !
11 m.à.j 10/7/2009: generation of a library for linking without the DLL.
12
13
14 Recovery of the sources
15
16     * Download the sources of version 2.6.0 which integrates recent changes.
17     * For the moment, it is a RC (Release Candidate), but the final version
18       should not delay.
19     * The use of the 2.6 is preferable with the 2.4-stable branch because many
20       bugs have been corrected.
21     * You will find the sources on the site of Freeglut:
22           o http://freeglut.sourceforge.net/
23
24
25 Objectives and preparation
26 Objectives
27
28     * We will create a DLL related to Cygwin, and an independent static library
29     * We will also create a dynamic library, allowing linking with the DLL.
30
31
32 List of generated files
33
34     * freeglut.dll: a traditional DLL for the dynamic linkage.
35     * libfreeglut.a: the static library. The final program is autonomous (at
36       least for OpenGL).
37     * libfreeglutdll.a: the dynamic library. The final program needs
38       freeglut.dll.
39
40
41 Preparation
42
43     * Extract the files from the freeglut archive.
44     * Go in the directory src (located at the root of the Freeglut directory),
45       and create a "Gl" sub-directory
46           o In this sub-directory, copy the files of the directory "include/Gl"
47
48     * Why is it necessary to create a "Gl" directory for compilation?
49           o I needed it to simplify things during my tests.
50           o If not you can create the repertories directly, and copy the files
51             as indicated in the point installation (see below).
52
53     * Do a little housekeeping in /lib:
54           o Erase all the references to the glut, so as not to conflict with the
55             linking.
56           o This stage is optional, you can also choose to do the housekeeping
57             only after a successful compilation of Freeglut.
58           o In your enthusiasm to clean things up, be careful not to erase the
59             library glu32.lib (not to be confused with glut32.lib).
60
61
62 Compilation
63
64     * Forget the "./configure, make, make install" triptych.
65           o It does not go at all with Cygwin.
66
67     * Here Makefile which will make the deal:
68
69 #Makefile for Freeglut 2.6.0-rc and Cygwin
70 #To place in the directory \93src/Common\94
71
72 sources=$ (wildcard *.c)
73 objs=$ (sources: .c=.o)
74 libname=freeglut
75
76
77 CFLAGS=-O2 - DTARGET_HOST_MS_WINDOWS - DX_DISPLAY_MISSING - DFREEGLUT_STATIC - I./
78 LDFLAGS=-lopengl32 - lgdi32 - lwinmm
79
80 nocyg=-mno-cygwin - mwindows
81
82 all: $ (objs)
83         #construction DLL related to cygwin1.dll
84         GCC $ (nocyg) $ (objs) - shared $ (LDFLAGS) - O $ (libname) .dll
85         Nm $ (libname) .dll  | awk \93BEGIN {print \93EXPORTS\94} /T _glut/{sub (/^.*T _/,\94 \ T "); print}\94 > $ (libname) .def
86         dlltool --dllname $ (libname) .dll --input-def $ (libname) .def --output-lib lib$ (libname) dll.a
87
88         #construction static library independent of cygwin
89         rear Cr lib$ (libname) .a $ (objs)
90         #pas inevitably obligatory (creation of an index to accelerate the accesses)
91         ranlib lib$ (libname) .a
92
93 %.o: %.c
94         GCC $ (nocyg) - C $ (CFLAGS) $<
95
96 clean:
97         rm - F *.o $ (libname) .dll $ (libname) .def lib$ (libname) dll.a lib$ (libname) .a
98
99
100
101
102 Some remarks on the makefile
103
104     * This makefile creates a DLL, a static library (a file, in other words) and
105       the dynamic library which will allow the use of the DLL.
106
107     * Do not try to strip the static library! You may not be able to compile
108       applications with static library any more.
109           o On the other hand, you can strip the final executable obtained after
110             compiling your application.
111
112     * I chose to call the DLL and the libraries by their "true names":
113       freeglut.dll libfreeglutdll.a and libfreeglut.a.
114           o Script configures recreated (for reasons of compatibility with the
115             old GLUT library) glut.dll and libglut.a.
116           o During the my tests, I had conflicts with an authentic "glut" which
117             trailed in my "/lib". I decided to call the things by their name, in
118             order to avoid confusions.
119           o Nothing prevents you from renaming the DLL, if you need to use GLUT
120             programs which you cannot recompile.
121
122     * The dynamic library is generated starting from the DLL.
123           o For reasons of brevity, I used awk. It generates the export file
124             used by dlltool.
125           o The only notable thing is the selection of the functions whose name
126             starts with _glut, in order to avoid including in the dynamic
127             library the functions that are not related to freeglut.
128           o then, one uses dlltool in a very traditional way.
129
130 Nm $ (libname) .dll  | awk \93BEGIN {print \93EXPORTS\94} /T _glut/{sub (/^.*T _/,\94 \ T "); print}\94 > $ (libname) .def
131 dlltool --dllname $ (libname) .dll --input-def $ (libname) .def --output-lib lib$ (libname) dll.a
132
133
134
135
136 Installation
137
138     * Copy libfreeglut.a, libfreeglutdll.a into the Cygwin directory /lib.
139     * Copy freglut.dll in the system32 of Windows (this is practical, but not
140       clean!).
141     * Copy the files headers of Freeglut (/include/gl) into the Cygwin directory
142       /usr/include/Gl.
143     * Copy the files headers (always /include/gl) into /usr/include/mingw/Gl:
144       this is used for compilations with the flag - mno-cygwin, which uses the
145       includes in mingw.
146           o You may need to erase the old GLUT include files if you installed it
147             with Cygwin.
148
149
150 Use of the library
151
152     * We will test with the program shapes, found in progs/demonstrations/shapes
153           o -mno-cygwin is used to force the use of Mingw without the large
154             dependence cygwin1.dll.
155           o -mwindows is only used to remove the horrible Shell window (very
156             useful for the settling, on the other hand).
157           o -L. (note the period after the "L"): I left libfreeglut.a,
158             libfreeglutdll.a and freeglut.dll in the test directory, at the time 
159             of the tests.
160
161
162 Compilation of the static freeglut library, without cygwin
163
164     * All the simplicity lies in the define: -DFREEGLUT_STATIC
165           o It serves to obtain good decoration of the function names in the
166             imports of the lib Freeglut.
167           o You can test without and use a hex editor to see the differences
168             in the objects.
169     * attention with the order of the libraries: -lfreeglut (static) must be
170       before the declaration of the dynamic libraries.
171
172     * gcc shapes.c -L. -lfreeglut -lopengl32 -lwinmm -lgdi32 -mno-cygwin -mwindows -DFREEGLUT_STATIC
173
174
175 Compilation with DLL freeglut, without cygwin
176
177     * For the define, see the notices above
178     * The order of the libraries is no longer important.
179
180     * gcc shapes.c -L. -lopengl32 -lwinmm -lgdi32 -lfreeglut -mno-cygwin -DFREEGLUT_STATIC
181
182
183 Compilation with DLL freeglut, Cygwin
184
185     * This example is given only for reference, the topic of this ticket being
186       to get rid of Cygwin.
187           o Let us say that can be used to make the point (and later).
188
189     * gcc shapes.c -L. -lopengl32 -lwinmm -lgdi32 -lfreeglut
190
191
192
193 Where are the dooooocs?
194
195     * Freeglut is delivered with its documentation, more very up to date.
196           o It seems that there is a problem with the original GLUT
197             documentation. Not only it does not correspond completely to the
198             operation of Freeglut, but moreover, its author (Mark Kilgard)
199             copyrighted it. Its distribution is thus difficult.
200
201     * Jocelyn Fréchot undertook a levelling of the docs for version 2.6.0. One can find them on his site for the moment:
202           o http://jocelyn.frechot.free.fr/freeglut/
203
204
205 Something survived\85
206
207     * I also tested the recompiling of the demonstrations of the original lib
208       GLUT (peace with its ashes).
209           o Nothing in particular to be announced.
210
211     * Thank you with all the courageous maintainers for Freeglut, that one
212       believed dead, but which still move.