The Chromium OS Platform
Chromium OS has many userland programs and sub-projects that make up the "platform" of the system. You can find them listed (as well as more details on each one) in the main Packages page. This guide is about the platform those projects build off. It is meant as the authoritative guide when writing a new project (or updating an existing one). You should not deviate from the choices outlined here without a very very good reason (and chances are that what you think is a very good reason is really not).
Here are some explicit goals for the Chromium OS platform:
- We should align & share code with Chromium whenever possible.
- C++ is the language you should be using.
- Only use C when C++ is not a viable option (e.g. kernel/bootloader/etc...).
- Shell code is rarely acceptable beyond short snippets.
- Each platform project should align & share code whenever possible.
- Use the same build system.
- Use the same set of utility libraries.
Rather than have every package implement its own build system (scons, cmake, autotools, hand written makefiles, common.mk, etc...), The One True Build System we use is GYP. More details on how it integrates can be found in the Platform2 page.
We follow the various Google style guides for Chromium OS projects. For third party projects, you should follow the style that project has decided on.
- C++ - Chromium C++ Style Guide
- Python - Chromium OS Python Style Guide (a superset of the Google Python Style Guide)
- Shell - Chromium OS shell-script Style Guide
Inter-Process Communication (IPC)
Most communication between processes is done via D-Bus. See the "D-Bus best practices" doc for more information.
If you need to serialize data, either for reading back later (from disk/cache/etc...) or for passing to another process (via ipc/network/etc...), then you should use:
- IPC (local machine or network)
- dbus - for simple stuff, dbus itself includes marshaling of basic types
- protocol buffers (protobufs) - for larger/binary content, or when communicating via the network
- Reading/Writing to disk
- base::JSON* - for general saved runtime state and/or config files (reading & writing)
- base::IniParser - for simple config files (read only); but json is still preferred
First off, whenever you want to do some new that you suspect someone else has done already, you should look through Chromium's base library and Chromium OS library (libchromeos). We build & ship these in Chromium OS; see the libchrome page and libchromeos page for building against them.
Here is a common run down of functionality provided by libchrome that platform projects use:
|command line flags||base/command_line.h|
|file path manipulation||base/file_path.h|
|file read/write utilities||base/file_util.h|
|INI file reading||base/ini_parser.h|
For libchromeos, see the libchromeos page for and overview of the functionality implemented there.
In particular, you should avoid using:
If you want your program to gather & report statistics at runtime (like UMA stats), then you should use:
- metrics - the Chromium OS metrics library
Sandboxing (User/Process/etc... Isolation)
All daemons should always be run with as restricted permissions as possible. This often means using a dedicated UID/GID, chroots, and seccomp filters. This is all handled by:
- minijail - the Chromium OS jail manager
You should avoid /sbin/ and /bin/ and /usr/sbin/ paths. They are unnecessary and you should just stick to /usr/bin/.
Similarly, you should avoid /$(get_libdir)/ (e.g. /lib/).
You should avoid /opt/. It is for exceptional cases only (mostly non-public/binary-only projects).
You should use OpenSSL for crypto services. A few projects still use NSS, but the plan is to migrate away from that, so no new code should be using it.
Since you will of course be writing unittests for all of your projects, you should use (which is to say unittests are a hard requirement):