• Browse GIT
• View
• Edit
• Upload
• History
• Print

BuildSystemSpecifications

Specifications for the build system of LyX 2.1.0

What it should do, how the interface should be, what options does it provide, and implementation details regarding the actual build tools being used (currently autoconf and cmake).

1.  Terminology

The build system is referred to as `make' but in fact might be named differently.

The terminology used below might include terms that are rather unixy. For example, on Windows a directory is most often known as a folder. Directory structure refers to a folder hierarchy. Nevertheless, these specifications should try to be as cross-platform as possible.

The build system is aware of the `source' directory and the `build' directory. The source directory corresponds to the root of svn trunk (http://www.lyx.org/trac/browser/lyx-devel/trunk/) or of a svn branch (e.g., http://www.lyx.org/trac/browser/lyx-devel/branches/BRANCH_2_0_X), where one finds the README and INSTALL files.

• By default, the build directory and the source directory are the same. This corresponds to an in-source build.
• The build directory can be changed by the user to something different from the source directory. This corresponds to an out-of-source build.

2.  Directory structure and paths

The following directory structure is obtained after a successful build.

<build dir>/bin

Executable files, without suffixes

<build dir>/lib

Support files: configure.py, chkconfig.ltx

3.  Build targets

Running `make' should result in building lyx and tex2lyx, while either one of these two could also be build individually using their corresponding target, e.g. `make lyx'. Build targets are also defined for common tasks such as: (re)merging .po files, creating tarballs for releases, etc.

• all (default)
• lyx
• tex2lyx

4.  Build output and build failures

The minimum amount of output should be printed to terminal. The name of the command being executed and the file being built constitute sufficient information to understand what is going on. It should be easy to spot warnings and the error causing a failed build.

• The command and file being processed are output to the terminal; the exact full command line is not necessary.
• All warnings and all errors should always be output to the terminal.
• If you run `make --silent', a successful, warning-free build produces absolutely no output to the terminal.
• A build stops on the first encountered error and outputs the standard error from the failed process to the terminal.

5.  Options

Here are the various options that we want in a build system. The actual implementation details are not relevant in this section. For example, some options might not be implemented at all. But the option names should be understood by the build system and the action should follow the description here, or give an error message as to why the action could not be obeyed.

Some options will optionally or conditionally take an input value. If no value is given by the user, the option is merely turned `on', unless a value is required, in which case the build system should stop with an error message.

version suffix

A string added as a suffix to the names of the installed binaries. By default, it is an empty string. If the option is turned `on' without a value, then use this default string: a dash, followed by the version number, optionally followed by "alpha|beta|rc|svn" and a number indicating the prerelease. For example: "-2.1.0svn" for current trunk, "-2.1.0alpha" for an alpha prerelease, "-2.1.0rc3" for the third release candidate, "-2.1.0" for the released version.

6.  Implementation details

Here are implementation details for autoconf and cmake.

For autoconf, options are passed to `configure' in the following way: --with-<option>[=<value>], where <option> is one of the option names listed above, with each space in the option name replaced by a dash (-).

For cmake, options are passed to `cmake' in the following way: -D<OPTION>[=<value>], where <OPTION> is one of the option names listed above, capitalized, and with each space in the option name replaced by an underscore (_).

7.  Categories

Category: Development LyX_2_1