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