Beginners guide to SGE
- 1. Intro
- 2. Compiling SGE
- 3. Using SGE
- 4. How to distribute your project
1. Intro
This is a small guide about how to compile and use SGE in your own project. It's mostly
aimed at Unix/Linux developers but others can probably find some information in here too.
This guide also assumes that you have a working version of SDL (and FreeType if you want
to use TT fonts in SGE) installed on your system (see the "README" file for more
information about this).
2. Compiling SGE
First we need to download the latest release. It's available under "Download" at the SGE
homepage:
http://www.etek.chalmers.se/~e8cal1/sge/index.html or
http://home.swipnet.se/cal_home/sge/index.html.
Save the sgeXXXXXX.tar.gz file somewhere and open a terminal and go to the directory
where you saved it. Unpack the file ('tar zxfv sgeXXXXXX.tar.gz') and you will have a new
directory with the SGE source code inside.
We will now take a closer look at the file "Makefile.conf", where you can customize SGE to
suite your system. Open this file with a text editor and at the top of the file you will see:
#C_ONLY = y
#NOTTF = y
#USE_IMG = y
#NO_CLASSES = y
#QUIET = y
By removing the comment symbol ("#") you can change some build options. These options
are documented in the "README" file but it's probably best to leave them as they are. Three
of them, however, can be worth changing.
Change "NOTTF" if you DON'T have FreeType 2 installed on your system. Most modern
systems do have FreeType 2 installed but you may need to install the dev package for it. The
easiest way to do this is to start the package manager for your Unix/Linux distribution and
search for "FreeType" and install all 2.x packages.
Change "USE_IMG" if you have the SDL_Image library installed. Some modern systems
have this library but you may need to install the dev package for it (see above).
Change "QUIET" if you don't want the makefile to output any SGE specific messages. More
about this later.
A bit further down in "Makefile.conf" you can also change compilers. It's however
recommended to leave them as they are.
Now you're ready to compile SGE! Make sure that you're standing in the root SGE directory
(sgeXXXXXX/). If you just want to test SGE and its examples you should now run 'make'
(or whatever GNU make is called on your system), but if you want to install SGE on your
system then you should run 'make install'. If something goes wrong under the compilation
there's probably something wrong with your SDL or FreeType installations.
You should test the examples when you have finished compiling SGE. Enter the directory
"examples/" and run "make", this will build all examples. Read the "README" file in this
directory for more information about the examples.
3. Using SGE
In this part of the guide I'll assume that you have installed SGE with "make install".
First create a directory for your new project (e.g. 'mkdir myproject'), in this directory we'll
create two files: "Makefile" and "myproject.cpp".
You should put something like this in "Makefile":
# Makefile for myproject
CXX=g++
CFLAGS =-Wall -O3 $(shell sdl-config --cflags)
LIBS = -lSGE $(shell sdl-config --libs)
TARGETS = myproject #change this to your project name
OBJECTS = $(addsuffix .o, $(TARGETS))
all: $(TARGETS)
$(TARGETS): %:%.o
$(CXX) -o $@ $< $(LIBS)
$(OBJECTS): %.o:%.cpp
$(CXX) $(CFLAGS) -c $<
clean:
@rm -f *.o $(TARGETS)
or if you have more complex project with multiple .cpp files that each have a corresponding .h
file:
# Makefile for mycomplexproject
CXX=g++
CFLAGS =-Wall -O3 $(shell sdl-config --cflags)
LIBS = -lSGE $(shell sdl-config --libs)
OBJECTS = main.o foo.o bar.o #every .cpp file in your project but replace .cpp with .o
all: $(OBJECTS)
$(CXX) -o mycomplexproject $(OBJECTS) $(LIBS)
$(OBJECTS): %.o:%.cpp %.h
$(CXX) $(CFLAGS) -c $<
clean:
@rm -f *.o mycomplexproject
Well, it's all a bit of black magic but for now I assume that you used the first Makefile
example (for more information about GNU make black magic please read its manual).
Finally we have to put some C/C++ code into the "myproject.cpp" file, e.g. this very simple
program:
/* A very simple SDL/SGE program */
#include "SDL.h"
#include "sge.h"
int main(int argc, char** argv)
{
/* Init SDL */
SDL_Init(SDL_INIT_TIMER|SDL_INIT_VIDEO);
/* Set window title */
SDL_WM_SetCaption("Testing", "testing");
/* Initialize the display */
SDL_Surface *screen;
screen = SDL_SetVideoMode(640, 480, 16, SDL_SWSURFACE);
sge_FilledRect(screen, 20,20, 620,460, 255,0,0);
SDL_Event event;
do{
/* Wait for user input */
SDL_WaitEvent(&event);
if(event.type == SDL_KEYDOWN && event.key.keysym.sym == SDLK_ESCAPE)
break;
if(event.type == SDL_QUIT)
break;
}while(true);
SDL_Quit();
return 0;
}
This is a very simple program without any error checking. Don't try this at home, always
check for errors!
Now then, to compile your project just run "make". Easy eh?
4. How to distribute your project
It's important to remember that SGE is licensed under the GNU Lesser General Public
License, which means that you can't link any non-GPL or non-LGPL code directly to it. In
that case you MUST link to a shared library version (under Unix libSGE.so and under Win32
SGE.dll). You must also include a notice in your distribution that you're using SGE (and
SDL!) and where the source code for SGE can be found. Also note that you might be using
other libraries too that SGE and SDL depend on (e.g. libpthread and libfreetype).
But if your project is licensed under the GPL or LGPL then you're free to use SGE (and SDL)
in almost any way you want (e.g. copy&paste code directly from SGE).
Below are some hints about how to include SGE in a source distribution of your project.
The do-it-yourself method
The easiest way to use SGE in your source distribution is to tell the user to download and
install SGE him/her-self. This is the most common way.
The include-it method
It might be a bit frustrating for the user to download every library him/her-self, especially
smaller libraries like SGE. One way to solve this is to include the SGE source code directly.
Place the sge*.cpp, sge*.h, Makefile* and License files in a new directory (i.e. sge/) at the
root of your project. Please also include a short notice like:
This project uses the SGE library from http://www.etek.chalmers.se/~e8cal1/sge/index.html.
SGE is distributed under the GNU Lesser General Public License (LGPL - see the License
file for more information).
Now either tell the user to go to this directory and compile and install SGE him/her-self or do
it from your build system. Make sure that you modify the "Makefile.conf" to suite your
project, this way you can use it directly in your build system (if you use a pure make system
like the examples above). Then you can use a Makefile like this for your project:
# Makefile for foobar
include sge/Makefile.conf
CFLAGS =-Wall -O2 $(SGE_CFLAGS) -Isge/
LIBS =-Lsge/ -lSGE $(SGE_LIBS)
... (the rest of the Makefile goes here).
Also add this rule in the Makefile:
...
sgelib:
@(cd sge; $(MAKE))
...
and then add that rule like a dependency somewhere, something like:
...
all: sgelib $(TARGETS)
...
or if you used the more complex makefile example above:
...
all: sgelib $(OBJECTS)
...
well, you get the idea. It might also be a good idea to modify the clean rule:
...
clean:
...
@(cd sge; $(MAKE) clean)
...
Done! If you don't want "Makefile.conf" to output any SGE messages while building then
you should uncomment the "QUIET" option.
This will link your code statically to SGE so your project must be GPL/LGPL licensed for
this to work. If you want to link dynamically to SGE it might be better to ask the user to
compile and install SGE before building your project, but you might also automatically build
a shared version of SGE with "@(cd sge; $(MAKE) shared)" from your Makefile. Don't
forget to install SGE with "@(cd sge; $(MAKE) install)" when you install your project or else
your executables won't run. Some Unix systems (like Linux) also require that you run
"ldconfig" when you have installed new libraries.
Anders Lindström
Copyright © 1999-2001 Anders Lindström
Last updated 011116