Development/GeneralProgrammingGuidelines

    From The Document Foundation Wiki

    TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate

    General Programming Guidelines

    Object-Oriented Programming

    Some recommended books on getting started with the concepts of Object-Oriented Programming (OOP):

    C++ Introductions

    Some recommended resources on learning C++ basics:

    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.

    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 the Git website.

    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 or ask for someone to sponsor you.

    Code Conventions

    See the article Code Conventions.

    For outdated historical references, see The OpenOffice.org C++ coding standards and The OpenOffice.org code conventions.

    Getting code pointers and navigating the codebase

    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 into "Full Search" in OpenGrok 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.

    When running LibreOffice with the GDB debugger, you can say info types ^TypeName$ to get the file name and line number for the definition of a type.

    Some integrated development environments are able to display declarations and definitions from anywhere in the codebase. This functionality is made possible by the make vim-ide-integration build command. Consult the code navigation documentation of your IDE:

    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++17, as supported by the compilers mentioned in the README.

    Further developer hints

    Retrieved from "https://wiki.documentfoundation.org/index.php?title=Development/GeneralProgrammingGuidelines&oldid=751025"