C and C++

This describes C/C++-specific guidance for checking code into //piper/third_party.

IMPORTANT: Read go/thirdparty first.

Googlify

Googlify is a tool used to import open source C/C++ libraries. The tool locally compiles the imported library together with all dependent libraries outside the build tree and outside your machine's normal install directories, thereby logging the complete build processes. If you are able to successfully build this way, you will know that you have solved all dependencies necessary to import to //piper/third_party.

Googlify allows you to analyze the build log, create a BUILD file from that analysis, repackage all sources (including all temporary created files and configurations), make all include statements compatible with google3, and import the library into your Piper client. The tool will also generate a global rule that depends on all rules generated for your library. Last but not least, the tool will have generated two tests to verify that you can link and run the library both dynamically and statically. If you want to use this tool, check out go/googlify or AdventuresInThirdParty or contact emailremoved@. The tool resides in //piper/.../googlify.

Warnings in //third_party code

google3's C++ code is built with a large number of warnings enabled in both Clang and GCC. These warnings can be critical, so they always produce errors in google3 builds. When adding third-party C++ code to google3, you will have to address these warnings. You have two options: fix the code or suppress the warnings. If you're interested and motivated to fix any warnings that fire in the code (and maintain those fixes going forward, potentially sending them upstream), then please ensure you add a cleanup-tagged OWNER that we can send CLs to when enabling new warnings for google3, and see below for how to enable warnings from your header files. This is particularly relevant for projects that are being developed in //piper/third_party (not just synchronized from an external source), and for projects where the value of catching any potential bug is unusually high (for example, openssl). These projects benefit from running all diagnostics normally used for google3 code.

If you need to suppress some warnings, that is fine to do in //piper/third_party, but here are some guidelines and special tools.

  1. Please suppress warnings by turning them off completely, not by using -Wno-error to prevent the build from breaking. Using -Wno-error just creates noise in builds without fixing anything.

  2. If you don't have the resources or ability to fix warnings and hit very many of them, consider using '-w' to suppress all warnings rather than individually suppressing each one.

  3. There are special techniques to handle warnings that trigger when other people include header files from your code.

Because historically most projects in //piper/third_party suppress warnings, and in order to avoid littering projects using such code with -Wno-... in copts, Clang treats all the headers included via a path starting with third_party/ as system headers by default. This makes Clang ignore all the warnings from these headers when building projects both inside and outside of //piper/third_party.

Third-party projects will usually find their own headers through relative paths or -I paths. These headers are not considered system headers. If you are actively interested in fixing warnings in your third-party code’s header files, there are two options:

  • Opt-out of this feature completely by asking emailremoved@ to add --no-system-header-prefix=third_party/$YOUR_PROJECT/ to the global CROSSTOOL configuration. That way both the project and its users will get all normal diagnostics from the project’s headers.

  • Opt-out of this feature for your project builds only by adding copts=[‘-Xclang-only=--no-system-header-prefix=third_party/your_project/’] to the BUILD file for //third_party/$YOUR_PROJECT/. This way users of the project will not get warnings from the project headers, but the project itself will.

    NOTE: This is only needed if the project includes its headers via third_party/… paths. The --system-header-prefix option does not affect warnings from the headers included via includes=, -I, or relative paths. Warnings from the headers included via includes= paths are always suppressed. If a third-party project finds its own headers through relative paths or -I paths, it will always get warnings from its headers.

    NOTE: Specific warnings can always be disabled in the project’s BUILD file using copts = [‘-Wno-...’] (see http://linkremoved/ for an example).

Alternatively, you can leave everything as is and ignore all the warnings from your project’s headers both in the project's code and in the code using your project's headers.