156 lines
6.3 KiB
Plaintext
156 lines
6.3 KiB
Plaintext
lw-build-system Instructions
|
|
========================================================================
|
|
|
|
Introduction
|
|
------------
|
|
|
|
The build system is a set of shell scripts used to build various types
|
|
of object file. Each project consists of one or more modules. Source
|
|
files (committed to the repository) live in "src", with one subdirectory
|
|
per module. Object files (or other volatile output) lives in "obj".
|
|
Cleaning is simply a case of deleting the "obj" directory.
|
|
|
|
Only a minimal part of the build system is committed to the repository
|
|
for each project; enough to build the project if it is checked out or
|
|
downloaded as a tarball. The rest of the build system (needed for
|
|
actual development) is installed as symlinks, so that changes to the
|
|
build system do not necessarily require changes to the repository.
|
|
|
|
Creating a New Project
|
|
----------------------
|
|
|
|
Instantiating a new project is done with `lw-build-system/create.sh'.
|
|
Simply pass the project name as the first argument. (It can be called
|
|
with no arguments to display usage).
|
|
|
|
The `~/.lwbuildrc' file, created on the first call of the project
|
|
creation script, contains some variables which are used when
|
|
instantiating the empty project and module templates.
|
|
|
|
The `config' file in the root of the project directory is where
|
|
user-editable variables live. Variables are generally only set here if
|
|
they are not exported in the environment; this allows variables to be
|
|
overridden in a wrapper script, with the defaults specified.
|
|
|
|
This might be a good point to run `git-init-db', if you intend to use
|
|
the git SCM system.
|
|
|
|
Instantiating Modules
|
|
---------------------
|
|
|
|
(This can only be done if the development symlinks are installed).
|
|
|
|
The `scripts/module-create.sh' script will allow the instantiation of
|
|
new modules. Running it with no arguments will display usage; generally,
|
|
it will take the module type, language, and name. The name is used
|
|
directly as `src/${name}', and will also be the name of the output
|
|
binary.
|
|
|
|
As modules are instantiated, they add any required arguments (e.g.
|
|
${CFLAGS} or ${BINDIR}) into the `config' file.
|
|
|
|
The `src/${name}/build.*' files may be edited to alter build behaviour.
|
|
This includes adding arguments to the C compiler. Variables set in
|
|
`config' are available when these scripts are run.
|
|
|
|
There are a few conventions of note.
|
|
|
|
Anything that wishes to link against external libraries will usually use
|
|
two variables in `config' (libname_CFLAGS and libname_LIBS). If these
|
|
are produced by running $(libname-config --cflags) and $(libname-config
|
|
--libs), then lines suitable for `config' can be produced by running
|
|
`scripts/config-printflags.sh libname'.
|
|
|
|
An application module has an EXTRAS variable in its build.app into which
|
|
the libname flags are placed (in addition to any others). A library
|
|
module will need to export dependency information; this is done by
|
|
changing the module_DEP_CFLAGS and module_DEP_LIBS flags in `build.lib'.
|
|
The dependency information will be placed into the lib-config executable
|
|
installed along with the library.
|
|
|
|
Sometimes, it is useful to have compile-time options. Conventionally,
|
|
these will be placed into the `config' file, and will often have a name
|
|
such as CONFIG_DISABLE_FOO.
|
|
|
|
Building
|
|
--------
|
|
|
|
Individual modules can be built with `./make.sh ${name}'. They can also
|
|
be built by category; see `src/${name}/build.*'. The part of the
|
|
filename after `build.' can also be passed to `./make.sh'. This allows,
|
|
for example, all applications to be built (`./make.sh app'); or only
|
|
libraries to be installed (`./make.sh install-lib').
|
|
|
|
Setting the environment variable VERBOSE to 1 before running make.sh
|
|
will display some additional tracing output.
|
|
|
|
Versioning and Tagging
|
|
----------------------
|
|
|
|
The `version' file in the top level of the project directory contains
|
|
the overall package version. This information is exported to C
|
|
applications and libraries via the preprocessor as VERSION and
|
|
VERSION_{MAJOR,MINOR,MICRO}.
|
|
|
|
Library modules have a `soversion' file, entirely independent of the
|
|
top-level version, which is used to create symlinks as well as set the
|
|
soname of the library. The soname depends only on the major and minor
|
|
version, meaning that the micro version number can be bumped without
|
|
changing the soname.
|
|
|
|
`scripts/version.sh' can be run to bump version numbers automatically.
|
|
If the project is a git repository, it can also be used to create tags
|
|
and push changes to a central repository.
|
|
|
|
The version script takes a number of commands, and executes them in
|
|
order. The following commands may be used:
|
|
|
|
major, minor, micro
|
|
Bump the version number in the top-level `version'. Bumping the
|
|
minor version will clear the micro version; bumping the major
|
|
version will clear minor and micro.
|
|
|
|
libmajor, libminor, libmicro (1 argument)
|
|
Bump the soversion number in a library's `soversion', with the same
|
|
semantics as major/minor/micro. The argument is the library module's
|
|
name.
|
|
|
|
tag (git only)
|
|
If this is a git repository, creates a tag based on the contents of
|
|
`version'.
|
|
|
|
push (git only)
|
|
If this is a git repository, does a `git push' as well as a
|
|
`git-push --tags'. This is a good way to ensure that any tags you
|
|
create are pushed to a central repository (this normally needs to be
|
|
done separately).
|
|
|
|
Creating tarballs
|
|
-----------------
|
|
|
|
(This only works for git repositories).
|
|
|
|
`scripts/release.sh' can be run to create a tarball of the project. It
|
|
takes two arguments: the first is the version number (or git tag) of the
|
|
version to release, and the second the output directory. This will
|
|
create a source tarball, a documentation tarball if a doxygen module is
|
|
detected, and will also attempt to sign the tarballs with gpg (although
|
|
it is not a fatal error if this step fails).
|
|
|
|
Upgrading build system
|
|
----------------------
|
|
|
|
Sometimes, the nonvolatile parts of the build system (the static parts
|
|
that are committed to the repository) need to be upgraded as well. There
|
|
is a script to do this in the lw-build-system repository.
|
|
|
|
From the project base directory, run the script
|
|
`/path/to/lw-build-system/update.sh'. This only works if symlinks are
|
|
installed. It will create a patch file, which you should edit before
|
|
applying.
|
|
|
|
Unfortunately, the upgrade process is not perfect and will not detect
|
|
legitimate changes you have made to files such as `config' and modules'
|
|
`build.*' files. You will need to manually edit the patch to revert
|
|
false positives.
|