[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

8.3.1 Overall Structure

The makefile system was designed to be very modular. This means that there are separate submakefiles for each unit that have to be built. Besides, there is a system-dependent submakefile (referenced through the variable $(TARGET_MAKEFILE)), user settings submakefile (`mk/user.mak'), common definitions submakefile (`mk/common.mak') and several other minor submakefiles. The root `Makefile' (which is located in the root directory of Crystal Space source tree, `CS') takes care of including all other submakefiles as required.

Initially the makefile system is unconfigured. The configuration process is supposed to define the system-dependent submakefile and several other definitions required for building Crystal Space on host platform. During configuration phase a submakefile called `config.mak' is created (in the same directory where root makefile is located, `CS'). Here is a sample of `config.mak' for Linux:

 
# Automatically generated file, do not edit!
TARGET = linux
TARGET_MAKEFILE = libs/cssys/unix/linux.mak
MODE = debug
USE_PLUGINS = yes
PROC = X86
CXX = gcc
CFLAGS.CONFIG += -mpentium -march=i586
CFLAGS.CONFIG += -fno-exceptions
CFLAGS.CONFIG += -fno-rtti
X11_PATH = /usr/X11R6

As you can see, the first statement defines the `TARGET' platform and the second defines the system-dependend submakefile. The `MODE' variable defines the default build mode (debug, profile or optimize). `USE_PLUGINS' tells whenever we will or will not use dynamic-linked libraries. (On platforms that do not support dynamic linking, system-dependent submakefile often automatically perform `override USE_PLUGINS=no' on your behalf.) The following statements defines several minor host platform and operating system characteristics such as processor type, C++ compiler, X-windows include path, and several optimization switches that are supported by compiler.

The system submakefile defines everything that is host platform/compiler dependent--the system-dependent libraries (for example, some Unix platforms require the math library `-lm' in order to use several math functions required by Crystal Space), the C/C++ compiler flags (separate for optimize, debug and profile modes) and so on. The system submakefile is included several times; the reason is that there are (system/compiler dependent) definitions that should be defined at the top of makefile, in the middle and so on. To differentiate between them a variable called `MAKESECTION' is used. For example, at the top of root makefile it is already needed to know which operating system, compiler, and processor we are running on. For this, the root makefile does the following:

 
MAKESECTION=rootdefines
include mk/subs.mak

The `mk/subs.mak' makefile is a special makefile that takes care of including all submakefiles: system-dependent and submakefiles for all drivers and applications; in our case we care only about system submakefile; effectively `include mk/subs.mak' turns into:

 
-include $(TARGET_MAKEFILE)

In $(TARGET_MAKEFILE) we check the `MAKESECTION' variable, and execute appropiate makefile statements. In our case:

 
ifeq ($(MAKESECTION),rootdefines)
PROC=X86
OS=LINUX
COMP=GCC
endif # ifneq (,$(findstring defines,$(MAKESECTION)))

Note that for some operating systems processor is defined directly in `config.mak' (it is detected in configure phase), so for such systems `PROC=' is not defined in rootdefines section.

For building something the root makefile runs a submakefile called `mk/cs.mak'. Note that `cs.mak' is not included but is run as a separate make process using `$(MAKE) mk/cs.mak args' command. This means that all definitions made for root makefile are ignored in `cs.mak', so `cs.mak' needs again to include `mk/subs.mak' in appropiate places with appropiate values for `MAKESECTION'. For example, to build csutil library, root makefile executes the following command:

 
$(MAKE) -f mk/cs.mak csutil

Currently the following values of `MAKESECTION' are used:

Used in root `Makefile'.
confighelp
The system submakefile is included from root makefile to define the various "help" messages which the makefile can display.
rootdefines
Define all the variables required by the root makefile
roottargets
Define all additional targets required by the root makefile

Used in `cs.mak'.
defines
Define all variables that are required for building any targets--the C/C++ compilers, flags and so on.
postdefines
Define any variables that depend on other variables.
targets
Define targets in addition to those in `cs.mak'; for instance, a library, a driver, an executable and so on.

Note that `MAKESECTION' variable is used not only in system-dependent submakefile. All submakefiles uses it; for libraries, for drivers and so on.

Each system-dependent submakefile defines a variable called `PLUGINS' which contain references to all drivers that are supported by this platform. The drivers are referenced by their directory name inside `libs/' subdirectory. For example, a `PLUGINS' variable that refers to the software X-windows 2D driver and to the software 3D renderer would look like this:

 
PLUGINS += video/canvas/softx video/canvas/linex

To find the submakefiles for drivers, `plugins/' is prepended to all components of `PLUGINS'; `/*.mak' is appended; and a wildcard search is performed. A possible result of above expansion might be:

 
PLUGINS_SUBMAKEFILES=plugins/video/canvas/softx/x2d.mak
  plugins/video/canvas/linex/linex2d.mak

These submakefiles are included each time when `subs.mak' is included either into root makefile or into a submakefile.

To find the submakefiles for libraries, `subs.mak' looks for all submakefiles contained one level deep in the `libs/' directory (i.e. `libs/*/*.mak'). For example, it might look like this:

 
(~/CS)% ls libs/*/*.mak
libs/csengine/csengine.mak      libs/cssys/cssys.mak
libs/csgeom/csgeom.mak          libs/csutil/csutil.mak
libs/csobject/csobject.mak      libs/csws/csws.mak

Submakefiles for applications located last, using the search mask `apps/*/*.mak', in this fashion:

 
(~/CS)% ls apps/*/*.mak
apps/blocks/blocks.mak          apps/mazed/mazed.mak
apps/map2cs/map2cs.mak          apps/simple/simple.mak
apps/levtool/levtool.mak        apps/walktest/walktest.mak

The library and application submakefiles also uses the `MAKESECTION' variable to insert statements into different places of the makefile. If you do not understand something, feel free to look through submakefiles that reside in all major directories of the Crystal Space source tree.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated using texi2html