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

8.2.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 platform-dependent submakefile (referenced through the variable $(TARGET_MAKEFILE)), user settings submakefiles (`mk/user.mak' and the optional `mk/local.ma'), common definitions submakefile (`mk/common.mak') and several other minor submakefiles. The top-level `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 build system is unconfigured. The configuration process identifies platform facilities and peculiarities and determines the platform-specific submakefile to use, as well as several other definitions required for building Crystal Space on a particular platform. During configuration phase a submakefile called `config.mak' is created in the top-level build directory. Here is a small extract of a `config.mak' created for Unix:

 
# Automatically generated file, do not edit!
TARGET = unix
TARGET_MAKEFILE = libs/cssys/unix/unix.mak
MODE = optimize
USE_PLUGINS = yes
PROC = X86
CXX = gcc -c
CFLAGS.optimize += -mpentium -march=i586
CFLAGS.SYSTEM += -fno-exceptions

As you can see, the first statement defines the `TARGET' platform and the second defines the platform-specific submakefile. The `MODE' variable defines the build mode (optimize, debug, or profile). `USE_PLUGINS' tells whenever we will or will not use dynamic-linked plugin modules, as opposed to linking all modules directly into the application as one monolithic entity. The following statements defines several minor host platform and operating system characteristics such as processor type, C++ compiler, and several optimization switches that are supported by compiler. In practice, a real `config.mak' will contain a good deal more information which was discovered by the configuration process.

The platform-specific submakefile defines features that are common for that type of platform, but does not specify any peculiarities about a particular installation. Instead, the configuration process figures out the pecuriarities of your system and sets up `config.mak' to reflect them. The system submakefile is included several times; the reason is that there are platform-specific definitions that should be defined at the top of each makefile, in the middle and so on. To differentiate between them a variable called `MAKESECTION' is used. For example, early in the root makefile it is necessary to know which operating system, compiler, and processor we are running on. For this, the root makefile does the following:

 
MAKESECTION=rootdefines
include $(SRCDIR)/mk/subs.mak

The `mk/subs.mak' makefile is a special makefile that takes care of including all submakefiles: platform-specific and submakefiles for all plugins, libraries, and applications. In our case we care only about platform-specific submakefile; effectively `include mk/subs.mak' invokes:

 
-include $(SRCDIR)/$(TARGET_MAKEFILE)

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

 
ifeq ($(MAKESECTION),rootdefines)
SOMEVAR=somevalue
OTHERVAR=othervalue
endif # ifneq (,$(findstring defines,$(MAKESECTION)))

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 via `$(MAKE) -f mk/cs.mak args'. 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 appropriate places with appropriate values for `MAKESECTION'. For example, to build the `csutil' library, the top-level 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 platform-specific submakefile is included from top-level makefile to define the various "help" messages which the makefile can display.
rootdefines
Define all the variables required by the top-level makefile.
roottargets
Define all additional targets required by the top-level 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 the platform-specific submakefile, but in all submakefiles; for libraries, for plugins, and so on.

Each platform-specific submakefile augments thee value of a variable called `PLUGINS' which contain references to all platform-specific plugins that are supported by this platform and which were not detected automatically by the configuration process. The drivers are referenced by their directory name inside `CS/plugins' subdirectory. For example, a `PLUGINS' variable that refers to the XFree86 shared-memory extension would look like this:

 
PLUGINS += video/canvas/xextshm

To find the submakefiles for plugins, `$(SRCDIR)/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 = video/canvas/xextshm/xextshm.mak

These submakefiles are included each time `subs.mak' is included either into the top-level makefile or into a submakefile.

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

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

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

 
(~/CS)% ls apps/*/*.mak
apps/demo/demo.mak
apps/walktest/walktest.mak
apps/examples/cswseng/cswseng.mak
apps/import/map2cs/map2cs.mak
apps/tutorial/simple1/simple1.mak
apps/tutorial/simple2/simple2.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