The setup requirements for Google's tools are often different than the setup requirements of the imported code. All Google engineers should be able to use the imported code just by running the build tool.
General language guidance
Many languages have special subdirectories where the code resides. These include:
Dart: //third_party/dart
.NET: //third_party/dotnet and //third_party/dotnet_src
Emacs Lisp: //third_party/elisp
Go: //third_party/golang
Haskell: //third_party/haskell
Java: //third_party/java and //third_party/java_src
JavaScript: //third_party/javascript
Lua: //third_party/lua
Common Lisp: //third_party/lisp
Objective-C: //third_party/objective_c
PHP: //third_party/php
Puppet: //third_party/puppet
Python: //third_party/py
R: //third_party/R
Ruby: //third_party/ruby
Swift: //third_party/swift
Mixed language code can go into //third_party without needing to be in a
subdirectory.
Package naming
Typically, the package name is based on the repository name from whatever site you retrieved the code. But Blaze doesn't support the use of hyphens or periods in names, so replace those with underscores.
Correct BUILD files, Blaze BUILD files only
IMPORTANT: All BUILD files in //third_party need to be analyzeable by blaze. In
practice, you can tell if your BUILD file is correct by running blaze build
--nobuild //third_party/your/package/....
Blaze can't process Bazel BUILD files, so if the code you're importing uses Bazel you should remove these BUILD files (alternatively, rename them to BUILD.bazel)
This doesn't mean your project has to build! This just means that your BUILD file has to be analyzeable (though, you really should not have a broken build - we don't run go/sensenmann in //third_party, so keeping dead things tidy is a package owners responsibility).
Why do this? Because there are tools that operate on the //third_party BUILD graph, and if your BUILD file can't be handled by blaze, those tools cannot work properly.
Language-specific guidance
Some languages use specific strategies to make your job easier and your code more reusable.
Unsupported languages
Some languages aren't officially supported at Google (see go/newlanguages). Support for them is typically ad-hoc, but they are still required to follow third-party guidelines. For example: not including binary objects in language-specific subdirectories and adhering to the One Version Policy.
The following languages are unsupported but have their own additional third-party policies:
IMPORTANT: Do not add dependencies to any projects using unsupported languages in your production code.
Best Practices
- Setup a go/blueprint file to clearly document the package.
- Setup go/Presubmit to make sure your code isn't broken accidentally.
- Add a
bugs:entry to your METADATA file. If an existing component or hierarchy doesn't make sense, you can request a new component via go/issuetracker-misc-component.