View source for Development/GenericBuildingHints

{{TopMenu}}
{{Menu}}
{{Menu.Development}}
{{Menu.Building}}

== Partition limitations ==

It's known that building on FAT(32)-formatted partitions don't work (the error is "Permission denied").

== First Build ==

The first time make is invoked, it will download the other git repositories needed (if any) and other external packages to be downloaded.

Building the application can take <code>8/number_cores</code> hours on a reasonably recent processor, and much more on Windows. 

<syntaxhighlight lang="bash">
$ ./autogen.sh
$ make check
</syntaxhighlight>
Although this will do, you might want to do a little more typing with 
<syntaxhighlight lang="bash">$ make check 2>&1 | tee build.log</syntaxhighlight>
This command is to save all the output of the make into a file (build.log), so that you can go back to it later to investigate if needed. Also with a fresh git clone, downloading and corresponding make might take some time. To avoid accidental killing of the process, one can use <code>nohup</code> make as follows: <code>nohup make &</code> which might nag <code>nohup: ignoring input and appending output to `nohup.out</code>. Then you can check progress with <code>tail -f nohup.out</code>.

If your build fails, check that you have satisfied the dependencies mentioned at the top of this page.

{{note|1=By default, build uses all cores available on system. This is nice to shorten the build time, but may make doing other tasks in parallel impossible.

To make it nicer, you may decrease priority of the build using <code>nice</code> command, to only take CPU time when there's no other tasks requiring CPU:

<syntaxhighlight lang="bash">$ nice make</syntaxhighlight>}}

== Rebuilds and partial builds ==

=== Re-build ===

If you modify the sources, or pulled your git repositories with the lastest update, you can rebuild by simply running :
<syntaxhighlight lang="bash">
$ make
</syntaxhighlight>

Sometimes, often because some header file got removed or renamed, it is necessary to do a full-blown rebuild.
<syntaxhighlight lang="bash">
$ make clean && make
</syntaxhighlight>

Note that during the build process, absolute softlinks (with resolved links in the cwd) are formed inside the build tree. So if you want to duplicate compiled code, choose to preserve links or you will triplicate it instead (breaking the stuff). This, however, makes the copy attack the source when the copy is used/cleaned, so use a script that bends the links after such a copy.

Also, if you add or remove the option <code>--enable-dbgutil</code>, you should do <code>make clean</code> and then <code>make</code> for a full rebuild. The reason is that binaries are incompatible. The fetched tarballs are not affected. If you do not do the full rebuild, you face failures in the build.

=== Partial build ===

Of course, due to the time it takes, a full rebuild is not the first recourse. When something goes wrong in a specific module, you can also rebuild just that module.

<syntaxhighlight lang="bash">
$ make <module>.clean
$ make <module>
</syntaxhighlight>

Modules are normally named after their directory. To get a list of all modules run:

<syntaxhighlight lang="bash">
$ make showmodules
</syntaxhighlight>

==== Single unit test run ====

If you need to run only a single test from a unit test module (including multiple tests), use this syntax:

<syntaxhighlight lang="bash">
$ make <CppunitTest_module> CPPUNIT_TEST_NAME=testFDO76163
</syntaxhighlight>

==== Faster single unit test module runs ====

Running a global make just to run a single unit test can take time. Normally a unit test name contains the module it belongs to. You can speed up the lookup by explicitly stating its directory:

<syntaxhighlight lang="bash">
$ make -C <directory> <CppunitTest_module>
</syntaxhighlight>

This will produce a more verbose output, but the result is the same.

== Building without tests ==

<code>make</code> does not perform any tests by default. Plain make should definitely '''not''' be used when building for the first time, because otherwise you may miss a problem with your setup that will give you a build with strange behavior that nobody else sees.

In the case when OpenCL tests (CppunitTest_sc_opencl_test) fail (e.g., due to faulty drivers on the development box), they may be disabled by setting the environment variable <code>SAL_DISABLE_OPENCL</code>.

== Verbosity and debug builds ==

=== Verbose build ===

If you want to get verbose output during build:

<syntaxhighlight lang="bash">
$ make verbose=t
</syntaxhighlight>

=== Getting debug output ===

If you want to get the output of OSL_TRACE() calls and other debug messages:

<syntaxhighlight lang="bash">
$ make -s dbglevel=2
</syntaxhighlight>

=== Getting debug symbols ===

If you want to enable symbols for profiling, debugging with gdb etc, but don't want to turn on debug outputs or change compiler optimization settings, run:

<syntaxhighlight lang="bash">
$ make -s ENABLE_SYMBOLS=true
</syntaxhighlight>

=== Partial debug build ===
Should you need to do a debug build of a module, to see more of the debugging messages during the LibreOffice run, you can add <code>debug=true</code> as a build's parameter, like:

<syntaxhighlight lang="bash">
$ make -s clean
$ make -s debug=true
</syntaxhighlight>

When you want to build the debug version for a fix set of modules you can use:
<syntaxhighlight lang="bash">
./autogen.sh --enable-debug --enable-symbols="<space separated list of modules terminated with '/' >"
</syntaxhighlight>
For details see the description of <code>--enable-symbols</code> in the output of <code>./autogen.sh --help</code>.

== Improving subsequent build performance ==

For details on <code>ccache</code>, see the OS-specific build instructions.

=== Fewer icon sets ===

Icon sets are recreated during each build (on Windows even before compiling the changed code(!)), thus disabling most of them saves time if there are only small code changes to compile otherwise.

Pick eg. the default theme on your system (like <code>elementary</code> or <code>colibre</code>), and add the following parameter to your <code>autogen.input</code>, then re-run <code>autogen.sh</code>:
<syntaxhighlight lang="bash">
--with-theme=<theme_name>
</syntaxhighlight>

A partial build, eg. <code>make sw</code> completely avoids rebuilding icon sets.

== Other useful commands you can use in the build system ==

=== autogen help ===

To configure your build run:

<syntaxhighlight lang="bash">
$ ./autogen.sh
$ ./autogen.sh --help
</syntaxhighlight>

There you can review a list of the build options. You can create a file called <code>autogen.input</code> to store these options permanently.

In the autogen.input file, give one option per line. You can temporarily comment out lines by adding # characters in front of them.

While some options in the autogen help are shown as taking values in quotes, the quotes are not used in autogen.input. So to provide a list of UI languages to build with in autogen.input, use <code>--with-lang=de ja ar</code>

A typical autogen.input file intended for LibreOffice development work might look like this:

<syntaxhighlight lang="bash">
--enable-dbgutil
--with-jdk-home=/path/to/jdk
</syntaxhighlight>

=== make help ===

To see other available options during partial module build, run:

<syntaxhighlight lang="bash">
$ make help
</syntaxhighlight>

Note that this is different from running '''make -h''', which lists commands for the GNU make itself.

=== make fetch ===

For your first build, a lot of external tarballs get downloaded before the real build starts. If you want to build offline, you can do:
<syntaxhighlight lang="bash">
$ make fetch
</syntaxhighlight>
before doing the build itself. This will download the other git repos and needed tar.gz packages.
Note that make will do this step anyways if you don't do it manually, but doing a make fetch the first time allow you to monitor the download activity.

=== make distclean ===

To remove the files that `configure' created (so you can compile the package for
a different distro or computer), type  
<syntaxhighlight lang="bash">
$ make distclean
</syntaxhighlight>
This can also be helpful if build starts failing after a major system upgrade.

== If build fails/if no debugging symbols available for a debug build ==

Check whether you have set the CFLAGS and CXXFLAGS environment variables in your environment, as ./autogen will inherit them and change the compilation behaviors.

Refer to the documentation of your command shell on how to unset the environment variables.

== Build system internals ==

:''See: [[Development/Build System]]''

[[Category:Development]]