Rules ForeignCc

Rules for building C/C++ projects using foreign build systems (non Bazel) inside Bazel projects.

Overview

Rules ForeignCc is designed to help users build projects that are not built by Bazel and also not fully under their control (ie: large and mature open source software). These rules provide a mechanism to build these external projects within Bazel's sandbox environment using a variety of C/C++ build systems to be later consumed by other rules as though they were normal cc rules.

Setup

To use the ForeignCc build rules, add the following content to your WORKSPACE file:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "rules_foreign_cc",
    # TODO: Get the latest sha256 value from the latest release on the releases page
    #       https://github.com/bazelbuild/rules_foreign_cc/releases
    #
    # sha256 = "...",
    strip_prefix = "rules_foreign_cc-0.3.0",
    url = "https://github.com/bazelbuild/rules_foreign_cc/archive/0.3.0.tar.gz",
)

load("@rules_foreign_cc//foreign_cc:repositories.bzl", "rules_foreign_cc_dependencies")

rules_foreign_cc_dependencies()

Please note that there are many different configuration options for rules_foreign_cc_dependencies which offer more control over the toolchains used during the build phase. Please see that macro's documentation for more details.

Rules

• cmake
• configure_make
• make
• ninja

For additional rules/macros/providers, see the full API in one page.

CMake

Building CMake projects

• Build libraries/binaries with CMake from sources using cmake rule
• Use cmake targets in cc_library, cc_binary targets as dependency
• Bazel cc_toolchain parameters are used inside cmake build
• See full list of cmake arguments below 'example'
• cmake is defined in ./tools/build_defs
• Works on Ubuntu, Mac OS and Windows(* see special notes below in Windows section) operating systems

Example: (Please see full examples in ./examples)

The example for Windows is below, in the section 'Usage on Windows'.

• In WORKSPACE.bazel, we use a http_archive to download tarballs with the libraries we use.
• In BUILD.bazel, we instantiate a cmake rule which behaves similarly to a cc_library, which can then be used in a C++ rule (cc_binary in this case).

In WORKSPACE.bazel, put

workspace(name = "rules_foreign_cc_usage_example")

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

# Rule repository, note that it's recommended to use a pinned commit to a released version of the rules
http_archive(
   name = "rules_foreign_cc",
   sha256 = "c2cdcf55ffaf49366725639e45dedd449b8c3fe22b54e31625eb80ce3a240f1e",
   strip_prefix = "rules_foreign_cc-0.1.0",
   url = "https://github.com/bazelbuild/rules_foreign_cc/archive/0.1.0.zip",
)

load("@rules_foreign_cc//foreign_cc:repositories.bzl", "rules_foreign_cc_dependencies")

# This sets up some common toolchains for building targets. For more details, please see
# https://github.com/bazelbuild/rules_foreign_cc/tree/main/docs#rules_foreign_cc_dependencies
rules_foreign_cc_dependencies()

_ALL_CONTENT = """\
filegroup(
    name = "all_srcs",
    srcs = glob(["**"]),
    visibility = ["//visibility:public"],
)
"""

# pcre source code repository
http_archive(
    name = "pcre",
    build_file_content = _ALL_CONTENT,
    strip_prefix = "pcre-8.43",
    urls = [
        "https://mirror.bazel.build/ftp.pcre.org/pub/pcre/pcre-8.43.tar.gz",
        "https://ftp.pcre.org/pub/pcre/pcre-8.43.tar.gz",
    ],
    sha256 = "0b8e7465dc5e98c757cc3650a20a7843ee4c3edf50aaf60bb33fd879690d2c73",
)

And in the BUILD.bazel file, put:

load("@rules_foreign_cc//foreign_cc:defs.bzl", "cmake")

cmake(
    name = "pcre",
    cache_entries = {
        "CMAKE_C_FLAGS": "-fPIC",
    },
    lib_source = "@pcre//:all_srcs",
    out_static_libs = ["libpcre.a"],
)

then build as usual:

bazel build //:pcre

Usage on Windows

When using on Windows, you should start Bazel in MSYS2 shell, as the shell script inside cmake assumes this. Also, you should explicitly specify make commands and option to generate CMake crosstool file.

The default generator for CMake will be detected automatically, or you can specify it explicitly.

The tested generators: Visual Studio 15, Ninja and NMake. The extension .lib is assumed for the static libraries by default.

Example usage (see full example in ./examples/cmake_hello_world_lib): Example assumes that MS Visual Studio and Ninja are installed on the host machine, and Ninja bin directory is added to PATH.

cmake(
    # expect to find ./lib/hello.lib as the result of the build
    name = "hello",
    # This option can be omitted
    generate_args = [
        "-G \"Visual Studio 15 2017\"",
        "-A Win64",
    ],
    lib_source = ":srcs",
)

cmake(
    name = "hello_ninja",
    # expect to find ./lib/hello.lib as the result of the build
    lib_name = "hello",
    # explicitly specify the generator
    generate_args = ["-GNinja"],
    lib_source = ":srcs",
)

cmake(
    name = "hello_nmake",
    # explicitly specify the generator
    generate_args = ["-G \"NMake Makefiles\""],
    lib_source = ":srcs",
    # expect to find ./lib/hello.lib as the result of the build
    out_static_libs = ["hello.lib"],
)

cmake

cmake(name, additional_inputs, additional_tools, alwayslink, build_args, cache_entries, data,
      defines, deps, env, env_vars, generate_args, generate_crosstool_file, install, install_args,
      lib_name, lib_source, linkopts, out_bin_dir, out_binaries, out_headers_only, out_include_dir,
      out_interface_libs, out_lib_dir, out_shared_libs, out_static_libs, postfix_script, targets,
      tools_deps, working_directory)

Rule for building external library with CMake.

ATTRIBUTES

A rule for building projects using the[Configure+Make][cm] build tool [cm]: https://www.gnu.org/prep/standards/html_node/Configuration.html

configure_make

configure_make(name, additional_inputs, additional_tools, alwayslink, args, autoconf,
               autoconf_env_vars, autoconf_options, autogen, autogen_command, autogen_env_vars,
               autogen_options, autoreconf, autoreconf_env_vars, autoreconf_options,
               configure_command, configure_env_vars, configure_in_place, configure_options, data,
               defines, deps, env, install_prefix, lib_name, lib_source, linkopts, make_commands,
               out_bin_dir, out_binaries, out_headers_only, out_include_dir, out_interface_libs,
               out_lib_dir, out_shared_libs, out_static_libs, postfix_script, targets, tools_deps)

Rule for building external libraries with configure-make pattern. Some 'configure' script is invoked with --prefix=install (by default), and other parameters for compilation and linking, taken from Bazel C/C++ toolchain and passed dependencies. After configuration, GNU Make is called.

ATTRIBUTES

A rule for building projects using the GNU Make build tool

make

make(name, additional_inputs, additional_tools, alwayslink, args, data, defines, deps, env,
     lib_name, lib_source, linkopts, out_bin_dir, out_binaries, out_headers_only, out_include_dir,
     out_interface_libs, out_lib_dir, out_shared_libs, out_static_libs, postfix_script, targets,
     tools_deps)

Rule for building external libraries with GNU Make. GNU Make commands (make and make install by default) are invoked with prefix="install" (by default), and other environment variables for compilation and linking, taken from Bazel C/C++ toolchain and passed dependencies.

ATTRIBUTES

A rule for building projects using the Ninja build tool

ninja

ninja(name, additional_inputs, additional_tools, alwayslink, args, data, defines, deps, directory,
      env, lib_name, lib_source, linkopts, out_bin_dir, out_binaries, out_headers_only,
      out_include_dir, out_interface_libs, out_lib_dir, out_shared_libs, out_static_libs,
      postfix_script, targets, tools_deps)

Rule for building external libraries with Ninja.

ATTRIBUTES

Rules Foreign CC

• boost_build
• cmake
• cmake_tool
• configure_make
• ForeignCcArtifactInfo
• ForeignCcDepsInfo
• make
• make_tool
• native_tool_toolchain
• ninja
• ninja_tool
• rules_foreign_cc_dependencies
• ToolInfo

boost_build

boost_build(name, additional_inputs, additional_tools, alwayslink, bootstrap_options, data, defines,
            deps, env, lib_name, lib_source, linkopts, out_bin_dir, out_binaries, out_headers_only,
            out_include_dir, out_interface_libs, out_lib_dir, out_shared_libs, out_static_libs,
            postfix_script, tools_deps, user_options)

Rule for building Boost. Invokes bootstrap.sh and then b2 install.

ATTRIBUTES

cmake

cmake(name, additional_inputs, additional_tools, alwayslink, build_args, cache_entries, data,
      defines, deps, env, env_vars, generate_args, generate_crosstool_file, install, install_args,
      lib_name, lib_source, linkopts, out_bin_dir, out_binaries, out_headers_only, out_include_dir,
      out_interface_libs, out_lib_dir, out_shared_libs, out_static_libs, postfix_script, targets,
      tools_deps, working_directory)

Rule for building external library with CMake.

ATTRIBUTES

cmake_tool

cmake_tool(name, srcs)

Rule for building CMake. Invokes bootstrap script and make install.

ATTRIBUTES

configure_make

configure_make(name, additional_inputs, additional_tools, alwayslink, args, autoconf,
               autoconf_env_vars, autoconf_options, autogen, autogen_command, autogen_env_vars,
               autogen_options, autoreconf, autoreconf_env_vars, autoreconf_options,
               configure_command, configure_env_vars, configure_in_place, configure_options, data,
               defines, deps, env, install_prefix, lib_name, lib_source, linkopts, make_commands,
               out_bin_dir, out_binaries, out_headers_only, out_include_dir, out_interface_libs,
               out_lib_dir, out_shared_libs, out_static_libs, postfix_script, targets, tools_deps)

Rule for building external libraries with configure-make pattern. Some 'configure' script is invoked with --prefix=install (by default), and other parameters for compilation and linking, taken from Bazel C/C++ toolchain and passed dependencies. After configuration, GNU Make is called.

ATTRIBUTES

make

make(name, additional_inputs, additional_tools, alwayslink, args, data, defines, deps, env,
     lib_name, lib_source, linkopts, out_bin_dir, out_binaries, out_headers_only, out_include_dir,
     out_interface_libs, out_lib_dir, out_shared_libs, out_static_libs, postfix_script, targets,
     tools_deps)

Rule for building external libraries with GNU Make. GNU Make commands (make and make install by default) are invoked with prefix="install" (by default), and other environment variables for compilation and linking, taken from Bazel C/C++ toolchain and passed dependencies.

ATTRIBUTES

make_tool

make_tool(name, srcs)

Rule for building Make. Invokes configure script and make install.

ATTRIBUTES

native_tool_toolchain

native_tool_toolchain(name, path, target)

Rule for defining the toolchain data of the native tools (cmake, ninja), to be used by rules_foreign_cc with toolchain types @rules_foreign_cc//toolchains:cmake_toolchain and @rules_foreign_cc//toolchains:ninja_toolchain.

ATTRIBUTES

ninja

ninja(name, additional_inputs, additional_tools, alwayslink, args, data, defines, deps, directory,
      env, lib_name, lib_source, linkopts, out_bin_dir, out_binaries, out_headers_only,
      out_include_dir, out_interface_libs, out_lib_dir, out_shared_libs, out_static_libs,
      postfix_script, targets, tools_deps)

Rule for building external libraries with Ninja.

ATTRIBUTES

ninja_tool

ninja_tool(name, srcs)

Rule for building Ninja. Invokes configure script.

ATTRIBUTES

ForeignCcArtifactInfo

ForeignCcArtifactInfo(bin_dir_name, gen_dir, include_dir_name, lib_dir_name)

Groups information about the external library install directory, and relative bin, include and lib directories.

Serves to pass transitive information about externally built artifacts up the dependency chain.

Can not be used as a top-level provider. Instances of ForeignCcArtifactInfo are encapsulated in a depset ForeignCcDepsInfo#artifacts.

FIELDS

ForeignCcDepsInfo

ForeignCcDepsInfo(artifacts)

Provider to pass transitive information about external libraries.

FIELDS

ToolInfo

ToolInfo(path, target)

Information about the native tool

FIELDS

rules_foreign_cc_dependencies

rules_foreign_cc_dependencies(native_tools_toolchains, register_default_tools, cmake_version,
                              make_version, ninja_version, register_preinstalled_tools,
                              register_built_tools)

Call this function from the WORKSPACE file to initialize rules_foreign_cc dependencies and let neccesary code generation happen (Code generation is needed to support different variants of the C++ Starlark API.).

PARAMETERS