Me wearing ridiculous goggles

Cobble C Syntax Reference

This is a reference to the BUILD file syntax of Cobble’s cobble.target.c plugin.

Targets

c_binary (leaf)

Defines an executable program or firmware image to be built using the C Production Model.

Florid example:

c_binary('turboencabulator',
  environment = 'freertos_m3',
  sources = [
    'frozzler.c',
    'transmangler.cc',
    'wetware.S',
  ],
  local = {
    'c_flags': [ '-O3', '-DENCABULATION=delicious' ],
  },
  deps = [
    ':frozzler_impl',
    '//chrono:mancer',
    '//third_party/raygun',
  ],
  extra = {
    'c_library_archive_products': False,
  },
)

Keyword arguments:

  • environment (required string): name of an environment, defined in BUILD.conf, that will be the top-level production environment. No interpolation support.

  • sources (optional list of string): a list of source files to be directly included in this binary. Some binaries may just rely on libraries and omit the sources list.

  • deps (optional list of string): target identifiers of anything required to build this binary. These are often libraries.

  • local (optional environment map): an appending delta describing the environment to use when compiling things in the sources list only. This will be applied after the using delta of all deps.

  • extra (optional environment map): an appending delta describing the environment to use when compiling anything transitively included in this binary, including deps and sources. (Note that most leaf targets, if included in deps, will ignore this delta and replace it with their own environment.)

c_library

Defines a bundle of code that can be included in other libraries or binaries using the C Production Model.

Florid example:

c_library('io',
  sources = [
    'output_stream.cc',
    'encoder.cc',
    'rot13.S',
  ],
  local = {
    'cxx_flags': [ '-I %(io_config_dir)s' ],
  },
  deps = [
    '//common',
    '//third_party/libprotobuf:lite',
  ],
  using = {
    'cxx_flags': [ '-I %(ROOT)s/io/include' ],
  },
)

Keyword arguments:

  • sources (optional list of string): a list of source files to be directly included in this library. Some libraries just compose other libraries and omit the sources list.

  • deps (optional list of string): target identifiers of anything required to build this library. These are often libraries themselves.

  • local (optional environment map): an appending delta describing the environment to use when compiling things in the sources list only. This will be applied after the using delta of all deps.

  • using (optional environment map): an appending delta describing the environment to use when compiling anything transitively depending on this library. This is not used when compiling the library’s own sources. (Note that most leaf targets will block upward propagation of using deltas, so this will in practice affect only the sub-DAG under a given leaf.)

Note that a c_library cannot easily affect the environment seen by its dependencies (it has no equivalent of c_binary’s extra delta). This is not a technical restriction, but a safety limitation designed to avoid accidentally creating unbuildable DAGs. It is possible to override this. Doing so is left as an exercise to the reader.

Library Output Options

Two environment keys affect how libraries are produced and linked.

If whole_archive is set to True in a scope, libraries defined in that scope will be linked with the -Wl,-whole-archive switch. This asks the linker to include every object file in a static archive, instead of being clever. Because the linker’s cleverness can miss data sections not referenced by text, this can be important for ensuring that it finds things like vector tables or preinit_array members.

Alternatively, if c_library_archive_products is set to False in a scope, libraries defined in that scope will not produce static archives at all. Instead, they will produce sets of object files (as they normally do), and propagate that list of objects to their users. This gets you the behavior change of whole_archive and also improves detection of duplicate symbol definitions, which are generally tolerated in static archives.

Why are there two options, and why are the both off by default?

  • When not using link-time garbage collection (together with e.g. -ffunction-sections -fdata-sections), both modes can significantly increase the size of your output.

  • Builds using static archives may be “tidier” and easier to inspect than builds composed of massive lists of objects. It’s a matter of taste.

Environment Keys

  • ar (string): path to the archiver. May be absolute or $PATH-relative.

  • aspp (string): path to the program to use for preprocessed assembly. This is generally the same as cc. May be absolute or $PATH-relative.

  • aspp_flags (list of string): flags to pass to the aspp program during object file production.

  • cc (string): path to the C compiler. Currently this program will also be used to link binaries. May be absolute or $PATH-relative.

  • c_flags (list of string): flags to pass to the C compiler during object file production.

  • c_deps_include_system (boolean, default True): normally, #include directives that reference system headers are included in Ninja’s dependency tracking. This is important for correctness if you ever update your toolchain or if you use -isystem for third-party headers you distribute. Setting this to False disables this behavior and may marginally increase speed if your disk is incredibly slow. Use of this option is strongly discouraged.

  • c_library_archive_products (boolean, default True): selects between static archives and bags-of-objects for libraries defined in its scope.

  • cxx (string): path to the C++ compiler. May be absolute or $PATH-relative.

  • cxx_flags (list of string): flags to pass to the C++ compiler during object file production.

  • link_flags (list of string): flags to pass to the linker when linking a binary. These flags are passed on the far left of the command line, before any input files are listed.

  • link_srcs (list of string): the actual list of inputs for linking a binary, accumulated during DAG traversal. This may contain switches like --whole-archive in addition to file paths. Because of this, file paths added to link_srcs should also be added to __implicit__. (This fact is only relevant if you’re hacking the C plugin.)

  • whole_archive (boolean, default False): for libraries using static archives, asks the linker to search the entire archive instead of being clever.

More Cliffle

By Topic