General Programming Guidelines
Some recommended books on getting started with the concepts of Object-Oriented Programming (OOP):
- Head First Object-Oriented Analysis and Design https://www.amazon.de/Head-First-Object-Oriented-Analysis-Design/dp/0596008678
- Head First Design Patterns https://www.amazon.de/Head-First-Design-Patterns-Freeman/dp/0596007124
Some recommended resources on learning C++ basics:
- "C++ Annotations" http://www.icce.rug.nl/documents/cplusplus/
- Stanford University Course CS106b "Programming Abstractions"
- youtube playlist of 2018 lectures: https://www.youtube.com/watch?v=IeVLwMS1nu8&list=PLT0wqqmbAFnfdRRCnzqY943MDyaNa3KSy (start with the first ~14 videos)
- youtube playlist of 2016 lectures: https://www.youtube.com/playlist?list=PLnfg8b9vdpLn9exZweTJx44CII1bYczuk (start with the first ~20 videos up to "Classes and Objects", you can skip over "recursion" and "backtracking" lectures the first time around)
- book for the lecture (but not a hard requirement): "Programming Abstractions" https://www.amazon.com/Programming-Abstractions-C-Eric-Roberts/dp/0133454843
- other resources for the course: https://web.stanford.edu/class/cs106b/index.shtml
- A quite complete C++ reference: https://en.cppreference.com/w/
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.
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. Once you've been asked (or asked for someone to sponsor you), you need to get an account.
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:
- The OpenOffice.org C++ coding standards.
- The OpenOffice.org code conventions. for an explanation of variable naming schemes etc.
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:
- 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
--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
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_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
For temporary debug output, use the
SAL_DEBUG macro. Commit hooks will prevent accidental committing of it.
SAL_INFO macros are inactive in a production build;
--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
tools/debug.hxx is obsoleted by
For more info, see the detailed description of the logging functionality.
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.
LibreOffice uses selected parts of C++17, as supported by the compilers mentioned in the README.
Further developer hints
- use resources on https://devcentral.libreoffice.org/
- Release Plan
- Some Notes on String Classes used in the source code
- Some Notes on Development/Sal Types
- How to deal with dictionaries
- Hints when developing more complex features
- Unit tests
- LCOV Code Coverage reports
- Clang static source code analysis
- Cppcheck static code analyzer
- Source Code Documentation
- Writing source code documentation
- Vim tips & tricks
- Build System
- FOSDEM 2012 slides of talks