Development/GeneralProgrammingGuidelines

From The Document Foundation Wiki
Jump to: navigation, search

General Programming Guidelines

Getting your first build done

Getting your first successful build of LibreOffice can be an intimidating and daunting task. Find a walkthrough that should guide you towards getting your first build finished on the Building On Linux or Building On Windows page. It is generally believed that building on Linux is somewhat easier.

If you want to compile LibreOffice without GUI support (e.g. for servers) you can find additional information on the headless build page.

Using Git for LibreOffice development

Git is a Distributed Version Control System (DVCS). It is a very powerful yet simple system, but if you are unfamiliar with DVCS, it can be confusing. Thankfully there are great resources on the Web to learn about Git. If you are not familiar with it, you should visit http://git-scm.com/ .

Most of LibreOffice source code is in the 'core' git repository, but few modules are in separate repository: 'translations', help', 'dictionaries' and 'binfilter'. In most cases you probably won't have to modify these repositories, but if you do you might want to read Git For LibreOffice Developers about the ./g tool that should help you to make this a bit less painful.

Getting and using commit access

In order to get commit access you need to be "sponsored". Once you've submitted patches and got yourself recognised this won't be a problem, but it's best to wait until you're asked. Once you've been asked (or asked for someone to sponsor you), you need to get an account.

Code Conventions

sal_Bool should be used only when it comes to UNO, and bool is preferred otherwise. More elaborate guidelines can be found on these pages:

Getting Code-Pointers

If you want to fix a bug or develop some nice feature you usually need to know the location in the source code. Here are two ways from UI to source:

  • Take a piece of text from the dialog (anything that is long enough, like "Width and spacing"), and put it to "Full Search" in [1] including the quotes (so that it does not find thousands of results). In this example, you get columnpage.ui. If you search for "columnpage.ui" you will get to sw/source/ui/frmdlg/column.cxx where the dialog is anchored.
  • Another way to find a dialog is the Help button. Click in your choosen dialog on the Help button to get the online help of this dialog. If you're lucky, you'll see an RID or something similar which you can search in opengrok. For example: Go to Impress -> Format -> Area, click the Help button and on the online help page you get RID_SVXPAGE_AREA:LB_AREA_TYPE which is what you want to search in the source.

Debugging

See How to Debug.

Assertions and Logging

To assert invariants of the code (that can only be violated if there are programming errors) use standard C/C++ assert. Production builds define NDEBUG, while --enable-debug/--enable-dbgutil do not. Do not follow an assert with code intended to mitigate the consequences of the detected programming error in production builds. For compile-time assertions, use C++11 static_assert.

To log warnings about unusual events (that the code nevertheless needs to handle in some way, like malformed input or I/O failures), use the SAL_WARN/SAL_WARN_IF macros from sal/log.hxx. It is generally better to report a detected problem up the call stack than to silence it locally. That is, a SAL_WARN is likely followed by a throw, and code should not catch and swallow exceptions that it cannot meaningfully handle.

To log other information useful for debugging, use the SAL_INFO/SAL_INFO_IF macros.

For temporary debug output, use the SAL_DEBUG macro. Commit hooks will prevent accidental committing of it.

The SAL_WARN/SAL_INFO macros are inactive in a production build; --enable-debug/--enable-dbgutil activates them. Which logging calls actually produce output is then further controlled by the SAL_LOG environment variable. See the documentation in sal/log.hxx for further details.

The functionality offered by osl/diagnose.h and tools/debug.hxx is obsoleted by sal/log.hxx.

For more info, see the detailed description of the logging functionality.

Workflow

Having a copy of the LibreOffice git tree where you do your work will speed up your compile time:

  • Tree1: Current master, always up to date. Here you could apply your changes from Tree2 and push them to origin/master.
  • Tree2: Your working tree. Here you do your changes. You update this tree once a week and do a complete build. After that you do your changes and rebuild. So you're unaffected by all the other changes in the master tree which often lead to time-consuming full rebuilds.

Baseline

LibreOffice uses selected parts of C++11, as supported by the following compilers:

  • Clang 3.1
  • GCC 4.7, though we try hard to remain compatible with GCC 4.6 for now, for Munich
  • MSVC 2012 until LibreOffice 4.4, MSVC 2013 after

Further developer hints