OBazl Conventions Last updated May 2, 2022

  • .bazelrc - always put this file in the project root directory; at a minimum, it should contain try-import .private/bazelrc.

    See Write bazelrc configuration files for more information.

  • Put the following in .gitignore:

    • .private/ - developers can use this subdirectory for shell scripts, data files, etc. that should not be under version control

      • Put the following in .private/.gitignore and put it under version control. This will put .private under version control (so all users can use it) but nothing it contains (except .gitignore) will be under version control.

        `*`

    • logs/

    • tmp/

  • Use .private/bazelrc to pass arguments to Bazel. Do not put it under version control.

    • Use :name suffixes to control sets of configuration settings ("profiles") at the command line using --config

  • Use .bazelignore to exclude irrelevant subdirectories from Bazel processing. For example, if you are adding Bazel support to a project that uses Dune, put _build in .bazelignore.

  • WORKSPACE.bazel, not WORKSPACE

  • Explicitly name your workspace - make workspace(name="foo") the first line of WORKSPACE.bazel (replacing foo with your workspace name). This will make log messages more decipherable, among other things.

  • Use WORKSPACE.bzl for extension code needed by WORKSPACE.bazel, such as fetch() functions that fetch language rules and external repositories.

  • BUILD.bazel, not BUILD

  • Use BUILD.bzl for package-local extension code.

  • Importing external repositories

    • If you import only a small number of repositories, and you do not expect others to import your repository, put the importing rules (http_repository, git_repository) in WORKSPACE.bazel

    • Otherwise, define one or more bootstrapping functions in WORKSPACE.bzl (note the extension, .bzl, not .bazel) responsible for fetching the repositories. See Bootstrapping for an example. Name them <lang>_fetch_rules (for fetching language support packages) and <lang>_fetch_repos for library repositories.

  • Mixed projects - using Bazel and another build tool (e.g. Dune) in parallel

    • If you want to keep Bazel files segregated, create a top-level bzl directory and keep Bazel extension files etc. there.

  • Use a tools subdirectory to store shell scripts and any other tools you want under version control.

    • Create a shell alias to enable easy access to the command log. Put the following (or something similar) in tools/aliases, and then source the file: $ source tools/aliases. Then $ bl will browse the log using less.

    alias "bl=less `bazel info command_log`"

Naming Conventions

  • Repository fetching functions:

    • <lang>_fetch_rules - for fetching rules packages

    • <lang>_fetch_repo, <lang>_fetch_repos - for fetching library repositories

    • alternative: <lang>_fetch_lib, <lang>_fetch_libs

  • primary target names should match package name. E.g. //foo/bar:bar

  • ocaml_module and ppx_module targets should capitalize the initial character (i.e. should match the OCaml module name). For example, ocaml_module(name="Foo", src="foo.ml"…​).

  • ocaml_signature targets should follow the same convention as for modules, suffixed by _cmi. For example: ocaml_interface(name="Foo_cmi", src="foo.mli"…​)

  • ocaml_ns_resolver target names should be suffixed by _ns.