Formatting source code

Native packages can define their own formatting rules.

For instance let’s consider a package defined this way:

PID_Package(
	AUTHOR My Name
	...
	FORMAT pid
	...
)

The source code defined into this package can be automatically formatted according to the rules defined in the pid format. this automatic formatting is based on clang-format tool.

To activate the formatter simply do:

pid cd <package>
pid format

Here are the already defined formats (at the moment this tutorial has been written). Some of them are standard formats provided by various open source projects or companies:

  • Chromium
  • LLVM
  • Google
  • Mozilla
  • Webkit
  • pid (formatting rules for the projects of PID framework)
  • pid11 (formatting rules for the projects of PID framework that are written in C++11)
  • rkcl (formatting rules for the projects of RKCL framework)

Then can all be found in official pid contribution space.

Creating new formats

If at a moment you need a specific format to apply to your packages youhave to define this format by yourself if it does not already exist. This is achieved by writting a new .clang-format.<name> file where <name> is the name of the new format.

For instance the file .clang-format.pid11 looks like:

---
Language:        Cpp
BasedOnStyle:  LLVM
PointerAlignment: Left
BreakBeforeBraces: Attach
ConstructorInitializerAllOnOneLineOrOnePerLine: true
AllowShortFunctionsOnASingleLine: false
SortIncludes:    false
IndentWidth:     4
AccessModifierOffset: -4
TabWidth:        4
...

These files follows the rules of clang format styles, there is nothing specific to PID here.

Guideline for writing new format style files

Basic steps are:

  • Choose the contribution space that contains the format style description. Let’s call it cs.
  • Edit a new file in <pid-workspace>/contributions/cs/formats/ with the pattern .clang-format.<name>, with <name> the same of the format style. Follow classic clang-format style decription guidelines.
  • Then commit this new file into cs repository
cd <pid-workspace>/contributions/cs
git add formats/.clang-format.<name>
git commit -m "format <name> added"
  • publish this format style in cs contribution space
cd <pid-workspace>
pid contributions cmd=publish space=cs
  • If cs was a contribution space where you cannot directly publish (push) your contributions, you have pushed to a fork of the contribution space repository. So remember that you need to propose a merge request, and wait this request is accepted by maintainers of cs original repository for your changes to be shared with others. This will be the situation if you want to contribute new formats into PID official contribution space.