Development/Gbuild

History
Gbuild was started in OOo times (like 2009) as a need to refresh the build system.

External tools
All external tools are checked against in the  script and you should have a look if you want an exhaustive list.

Prerequisites for building are handled for various OS flavors. Links are available on the main Development page.


 * Gbuild relies on GNU Make to work
 * Bash is required, although most shell scripts are POSIX-compliant (called by /bin/sh).
 * Perl and Python are also used during the build process

Build internal tools (self-built)

 * gcc-wrapper is a binary provided to redirect external modules builds requiring gcc under Windows or macOS to be redirected to our default compilers (resp. MSVC and g++ in Obj-C mode)
 * python helpers for gdb
 * concat-deps removes duplicate dependencies
 * some more scripts used for packaging, cleaning, platform specific stuff (see $SRCDIR/solenv/bin)

Middleware tools
Some come from external libs (xsltproc), others come from history (transex3).

All those are not part of a compiler.
 * l10n tools
 * transex
 * cfgex
 * rsc (module)
 * idlc
 * climaker
 * xrmex
 * windows setup tools
 * makecab.exe
 * msidb.exe
 * msiinfo.exe
 * msimsp.exe
 * msitran.exe

Architecture
Gbuild is stored in ./solenv/gbuild

Because we have more than 200 modules to build for a full product, we want to avoid duplicating work. We want because it is a Good Thing™, and also because a change in a workflow in a module is likely to be spread in all similar behaviors. So far:

In, you have the di/trigram used during make to identify module output during the build

Conventions & principles
If classes have a trigram, this shows they are "public", meaning they are called from modules make directly, not through the gbuild engine.


 * functions and vars are
 * is the constructor
 * If a function or a var contains  (double underscores), then it is a private item (internal only)
 * All functions working with lists end with an s. They all have a matching non-plural function that wraps the real call.
 * *_get_target functions give paths to files (often from a local list). The functions are defined in TargetLocations.mk

gbuild
Initialize many variables, transclude some vars from configure into gb_ ones.

AllLangHelp (ALH)
Uses HelpTarget Helper to get all help files at the right places when building a module

AllLangPackage
Handles creation of a bunch of packages with content dependent on language. The package files are placed into
 * 1) define rule to clean
 * 2) define gb_Foo_Foo to set up variables for one instance to build (constructor) and call there
 * 3) add foo to solenv/gbuild/gbuild.mk
 * 4) include in user build to actually use it:

$(eval $(call gb_Foo_Foo, instance_name))

Transversal tips for below tasks
I put this on top to be sure you know about them, but you should read them after viewing below tasks :)

Tips 1 to 3 from OOo wiki

Tip 1: Deliver to the solver
Usually there are some header files to be delivered to the solver and the header files, which located at $(SRCDIR)/module/inc. So you can use the Step 3 in Gbuild migration tutorial.

When you need to deliver some headers in source, you can create a file in the module root called Package_source.mk $(eval $(call gb_Package_Package,toolkit_source,$(SRCDIR)/toolkit/source)) $(eval $(call gb_Package_add_file,toolkit_source,inc/layout/core/bin.hxx,layout/core/bin.hxx)) ...
 * 1) deliver $(SRCDIR)/toolkit/source/ layout/core/bin.hxx to $SOLARVER/$INPATH/inc/layout/core/bin.hxx

When you need to deliver some utility files, such as *.xml, *cfg ..., you can create a file in the module root called Package_util.mk

$(eval $(call gb_Package_Package,toolkit_util,$(SRCDIR)/toolkit/util)) $(eval $(call gb_Package_add_file,toolkit_util,xml/toolkit.xml,toolkit.xml))
 * 1) deliver $(SRCDIR)/toolkit/util/tookit.xml to $SOLARVER/$INPATH/xml/toolkit.xml

Then don't forget to add this files in Module_toolkit.mk (in our case, for other modules, use the name of that module)

... $(eval $(call gb_Module_add_targets,tools,\ ...    Package_source \ Package_util \ ...       )) ...

Tip 2: Useful Variations
When you writing the makefile, you may need some pre-defined vars for your function. Here are some useful vars.

Note: Use gb_Library_OOOEXT instead of $(DLLPOSTFIX)$(DLLPOST)

Tip 3: Linked Library
For example, if you want to link with sysshell.lib in Library_sfx.mk, you can edit the file and add the library as below: ... $(eval $(call gb_Library_add_linked_libs,sfx,\ comphelper \ cppu \ ... syssh.uno  ... $(gb_STDLIBS) \ )) ...

Then, you can use make -sr to build, unfortunately there will be an error message: Cannot link against library/libraries sysshell. Libraries must be registered in Repository.mk.

As the hint, we can edit the Repository.mk, which is located at $SRCROOT, and add the below line:

... $(eval $(call gb_Helper_register_libraries,OOOLIBS, \ AppleRemote \ avmedia \ basegfx \ basebmp \ ... syssh.uno  ... $(gb_STDLIBS) \ )) ...

Usually, the thing will be over, however, some libs such as the example, another error will be there

Try `/bin/cp --help' for more information. make: *** [/home/int/....../unxlngi6.pro/lib/libsyssh.uno.so] Error 1

It is because the build system assume the library will begin with "lib"("i" in Windows), but some libraries come without the prefix, such as this one. So we need to change it in RepositoryFixes.mk

ifeq ($(OS),LINUX) gb_Library_FILENAMES := $(patsubst comphelper:libcomphelper%,comphelper:libcomphelp%,$(gb_Library_FILENAMES)) gb_Library_FILENAMES := $(patsubst cppuhelper:libcppuhelper%,cppuhelper:libuno_cppuhelper%,$(gb_Library_FILENAMES)) ...  gb_Library_FILENAMES := $(patsubst syssh.uno:libsyssh.uno%,syssh.uno:syssh.uno%,$(gb_Library_FILENAMES)) ... endif

I hope this tutorial gives you some useful tips with the new build system. If you find some other good tips, please to contribute here.

A new module of libreoffice
See templates in ./solenv/gbuild

An external project
See templates in ./solenv/gbuild

Gbuild cheat sheet
Some tips for a developer with very small knowledge on make system:
 * .PHONY: phony targets have no output files (they are actions rather than files).
 * Automatic variables:
 * $@ is the target filename, path included
 * $* is the target filename with no extension, path included
 * $< is the first prerequisite (the dependency that appears after the colon).
 * $? is the list of all prerequisites that are newer than the target (space-separated)
 * $^ is the list of all prerequisites
 * TO BE CONTINUED

See Gbuild Cheat Sheet for more