Build Lazarus Projects Reliably with lazbuild 3.0

You will build a Lazarus project or package from a Linux shell, select the intended target when needed, and verify which compiler and Lazarus configuration were used. The installed command here is Lazarus 3.0 from lcl-utils-3.0, package version 3.0+dfsg1-8build3.

Allow 10 to 20 minutes for a first build if dependencies are already installed. The first run can take longer because required packages and compiler units may need compiling. The examples use ordinary user permissions. Use sudo only for installing missing packages through your distribution's package manager, not for building your own source.

1. Check the installed builder

Start by confirming that the shell finds the expected executable and that it reports the expected major version.

$ command -v lazbuild
/usr/bin/lazbuild
$ lazbuild --version
3.0

The version option exits without building anything. If the command is missing, install the Lazarus utilities package supplied by your distribution. Do not copy the example path blindly: command -v tells you which executable your shell will actually run.

2. Build one Lazarus project

Change to a project directory and pass the .lpi file as the final argument. Replace the placeholder with the project you intend to build.

$ cd /path/to/project
$ lazbuild project.lpi

A Lazarus project is normally described by an XML .lpi file. lazbuild checks the project's package dependencies and compiles required packages first. Keep the build output: the first error is usually more useful than the final summary.

$ lazbuild project.lpi && echo "build succeeded"
build succeeded

3. Build a package or force a full rebuild

Pass a Lazarus package file when the unit you need is described by .lpk rather than a project file.

$ lazbuild /path/to/component/component.lpk

For a clean compiler pass over every project or package file, add -B or its longer form. This can be slower and will expose stale or missing source assumptions that an incremental build does not.

$ lazbuild --build-all project.lpi

By default, the builder also handles dependencies. Use --skip-dependencies only when those dependencies are already built and you deliberately want to avoid compiling them. The shorter form is -d.

4. Decide how dependencies receive a full rebuild

--build-all applies the full-build flag to the named project or package. Add --recursive when that full-build behaviour must also be applied to dependencies.

$ lazbuild --build-all --recursive project.lpi

These flags do not repair a dependency that is absent or incompatible. If the build fails, read the first missing unit or package path in the output, then check the project's package search configuration and installed Lazarus packages. Avoid switching to --skip-dependencies merely to hide that error: it can leave you with an apparently successful command that uses old compiled units.

5. Select the target deliberately

The installed 3.0 builder defaults to Linux, the gtk2 widgetset and x86_64 on this machine. A project can override those choices for one invocation.

$ lazbuild --operating-system=linux \
    --widgetset=gtk2 \
    --cpu=x86_64 \
    project.lpi

Use the short forms --os, --ws and --cpu if you prefer. Other target values are accepted by the installed command, but use only values supported by the project and its available compiler, LCL interface and libraries. A target override is not a cross-compiler installation.

For a project with named build modes, select one with --build-mode or --bm.

$ lazbuild --build-mode=Release project.lpi

The build mode name must exist in the project. If it does not, the command fails; it does not invent a mode.

6. Keep Lazarus configuration and IDE changes visible

Lazarus uses a primary configuration directory for user settings and a secondary directory for configuration templates. On this installation the defaults shown by lazbuild --help are /home/andy/.lazarus and /etc/lazarus.

$ lazbuild --primary-config-path=/path/to/test-config project.lpi
$ lazbuild --pcp=/path/to/test-config project.lpi

Use a separate primary path when testing configuration-dependent builds. The command may write updated project information after a build, including an incremented build number when the project is configured to do so. In the installed 3.0 command, --no-write-project prevents that project-file update.

7. Make noisy or quiet output useful

Use --quiet when a script needs less output, or --verbose when diagnosing package discovery and compiler choices. The installed command accepts either option more than once. For package search problems, --verbose-pkgsearch shows which package files it searches for and finds.

$ lazbuild --verbose-pkgsearch project.lpi
$ lazbuild --verbose project.lpi

If a build fails, repeat it with the narrowest useful diagnostic option and save the output for comparison. Do not discard the normal output before you know which dependency or target is wrong.