Add some documentation
This commit is contained in:
Laurence Withers
parent
4a57c03bc3
commit
894862ddd6
|
|
@ -0,0 +1,138 @@
|
|||
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).
|
||||
Loading…
Reference in New Issue