Build Environment Effort/Module Migration

From Apache OpenOffice Wiki
Jump to: navigation, search

Edit.png

Build Environment Effort

Quick Navigation

About this template


The progress of module migration is tracked here

How to convert an OOo module to the new Build Environment

Documentation note.png In CWS gnumake3 there are templates for various kinds of makefiles in solenv/gbuild/templates, which should make this task a lot easier.

Step 1: Get a makefile in the module root

Put a copy of the module makefile in your module root. This file is the same in all modules, so you can simply copy it over from an already migrated module. There is no need to do any modifications to this file.

Step 2: Declare the module

Create a file with the name Module_${NAME}.mk (Module_tools.mk in our case) in the module root and fill it with this basic content:

# ...
$(eval $(call gb_Module_Module,tools))
$(eval $(call gb_Module_add_targets,tools,\
))

Step 3: Declare the headers

Create a file in the module root called Package_inc.mk and declare the header to be delivered to the solver in it.

# ...
$(eval $(call gb_Package_Package,tools_inc,$(SRCDIR)/tools/inc))
$(eval $(call gb_Package_add_file,tools_inc,inc/tools/StringListResource.hxx,tools/StringListResource.hxx))
...

Then add the Package with the headers to the module in Module_tools.mk (in our case, for other modules, use the name of that module)

...
$(eval $(call gb_Module_add_targets,tools,\
    Package_inc \
))
...

Step 4: Add declarations for the libraries and executables

To create a library in the module, create a file Library_${NAME}.mk (Library_tl.mk in our case) and add the following content to it:

$(eval $(call gb_Library_Library,tl))

This declares the library with the name "tl".

$(eval $(call gb_Library_add_package_headers,tl,tools_inc))

We need to declare the package headers of the libraries. This ensures the headers to be in solver (called $(OUTDIR) according to GNU make code conventions in the new build system) before object files from libraries linking against this library are compiled. The first argument is the library name (a bit like the self argument in object-oriented Python) and the second is the package name we declared earlier.

$(eval $(call gb_Library_add_precompiled_header,tl,$(SRCDIR)/tools/inc/pch/precompiled_tools))

We also declare a precompiled header file (currently only used on Windows) if the library uses one. The first argument is again the library name, the second is the stem of the path to the PCH file. $(SRCDIR) expands to the OpenOffice.org source tree root directory (gbuild supports multiple source roots/"repositories" -- more on that in a later post).

$(eval $(call gb_Library_set_include,tl,\
    $$(INCLUDE) \
    -I$(OUTDIR)/inc \
    ...
))

Here we are declaring the include paths to use when compiling the objects of the library. $$(INCLUDE) expands to the old include paths, which, since we have not modified them yet, are the default paths.

$(eval $(call gb_Library_set_defs,tl,\
    $$(DEFS) \
    -DSHARED_LIB \
    ...
))

This is just the same for the defines.

$(eval $(call gb_Library_add_linked_libs,tl,\
    basegfx \
    comphelper \
    ... 
))

Here we declare the libraries we are linking against. In addition the setting the link flags it also sets the dependencies right:

  • Before an object of a library is compiled, all header of the library and all libraries it links against have to be delivered to the $(OUTDIR). This is why we explicitly declared the package headers of the library before.
  • Before an library is linked, all libraries it links against are linked and copied to the $(OUTDIR).
$(eval $(call gb_Library_add_exception_objects,tl,\
    tools/source/communi/geninfo \
    ...
))

Here we enumerate all the objects files are compiled with exceptions enabled, that should be linked into the library. For other types of objects there are the:

  • gb_Library_add_noexceptionobjects
  • gb_Library_add_cobjects and
  • gb_Library_add_objcxxobjects macros.

Finally we would need to do some platform specific fixes (like system libraries) to end up with this Library_tl.mk. Then the last thing to do is to add the file to the Repository.mk in the the source root:

$(eval $(call gb_Helper_register_libraries,OOOLIBS, \
    ...
    tl \
    ...
))

This allows other libraries to link against it by telling gbuild:

  • The name of the library on the various platforms.
  • The layer where the library will end up at runtime and thus how the rpath or its equivalent should be set on various platforms.

Repeat the steps for all executables and libraries.

Step 5: Components

A library which contains UNO service(s) needs a component file for passive service registration.

 $(eval $(call gb_Library_set_componentfile,tk,toolkit/util/tk))

Be careful! You have to adapt the path to the component file in makefile.mk located in postprocess/packcomponents. Otherwise packcomponents cannot find your component file resulting in a broken build.

 my_components = \
     abp \
     adabasui \
     ...
     component/toolkit/util/tk \
     ...

Step 6: Unit tests

Documentation note.png Unit test support is new in CWS gnumake3.
  • For each CppUnit test, create a CppunitTest_foo.mk makefile from the template.

In Module_foo.mk, use gb_Module_add_check_targets to activate the test.

  • For each unoapi/complex test, create a JunitTest_foo.mk makefile from the template.

In Module_foo.mk, use gb_Module_add_subsequentcheck_targets to activate the test.

Step 7: Finishing touches

  • Add the migrated module to the Module_ooo.mk at the source root.
  • Put a copy of the bridge makefile in the prj directory of the module for dmake.
  • Clear the prj/build.lst, add just the prj directory for the bridge makefile.
  • Clear the prj/d.lst and remove the old dmake makefiles.

Done!

I hope this tutorial gives you a good start with the new build system. If you are interested in migrating a module and you do not care which one it would be great if you chose one of the "late" modules build after svx. Because once we have all modules from svx up migrated, we can build those in one GNU make process and get rid of build.pl for that part. To find out which modules are "late" take a look at the split build analysis Mathias published in the Build Environment Effort section of the OpenOffice.org wiki or at the build timeline I created as a record of the status quo.

I have spend quite some time with the new build system and might already take some concepts for granted in the tutorial above that are not obvious for a newcomer. So if anything of the above is unclear do not hesitate to ask and comment. With the introduction of gnumake2 I will create a copy of the tutorial in the OpenOffice.org wiki so that it can be expanded and refined with your valued input.

So happy hacking with the new build system!

Personal tools