This describes C/C++-specific guidance for checking code into //piper/third_party.
IMPORTANT: Read go/thirdparty first.
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.
Please suppress warnings by turning them off completely, not by using
-Wno-errorto prevent the build from breaking. Using
-Wno-errorjust creates noise in builds without fixing anything.
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.
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
Clang treats all the headers included via a path starting with
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
-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
CROSSTOOLconfiguration. 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
//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
--system-header-prefixoption does not affect warnings from the headers included via
-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
-Ipaths, it will always get warnings from its headers.
NOTE: Specific warnings can always be disabled in the project’s
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.