Rules ForeignCc

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

Release	Commit	Status
main	fa1d617

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 a bazel debug message or the latest 
    #       release on the releases page: https://github.com/bazelbuild/rules_foreign_cc/releases
    #
    # sha256 = "...",
    strip_prefix = "rules_foreign_cc-fa1d617e5eb847f740bdd2660fa28e96f7ed566c",
    url = "https://github.com/bazelbuild/rules_foreign_cc/archive/fa1d617e5eb847f740bdd2660fa28e96f7ed566c.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
• meson
• 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'
• 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 16 2019\"",
        "-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, build_data, cache_entries,
      copts, data, defines, deps, env, generate_args, generate_crosstool_file, includes, install,
      install_args, lib_name, lib_source, linkopts, out_bin_dir, out_binaries, out_data_dirs,
      out_dll_dir, out_headers_only, out_include_dir, out_interface_libs, out_lib_dir,
      out_shared_libs, out_static_libs, postfix_script, targets, tool_prefix, tools_deps,
      working_directory)

Rule for building external library with CMake.

ATTRIBUTES

cmake_variant

cmake_variant(name, toolchain, kwargs)

Wrapper macro around the cmake() rule to force usage of the given make variant toolchain.

PARAMETERS

A rule for building projects using the Configure+Make build tool

configure_make

configure_make(name, additional_inputs, additional_tools, alwayslink, args, autoconf,
               autoconf_options, autogen, autogen_command, autogen_options, autoreconf,
               autoreconf_options, build_data, configure_command, configure_in_place,
               configure_options, configure_prefix, copts, data, defines, deps, env, includes,
               install_prefix, lib_name, lib_source, linkopts, out_bin_dir, out_binaries,
               out_data_dirs, out_dll_dir, out_headers_only, out_include_dir, out_interface_libs,
               out_lib_dir, out_shared_libs, out_static_libs, postfix_script, prefix_flag, targets,
               tool_prefix, 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

configure_make_variant

configure_make_variant(name, toolchain, kwargs)

Wrapper macro around the configure_make() rule to force usage of the given make variant toolchain.

PARAMETERS

A rule for building projects using the GNU Make build tool

make

make(name, additional_inputs, additional_tools, alwayslink, args, build_data, copts, data, defines,
     deps, env, includes, install_prefix, lib_name, lib_source, linkopts, out_bin_dir, out_binaries,
     out_data_dirs, out_dll_dir, out_headers_only, out_include_dir, out_interface_libs, out_lib_dir,
     out_shared_libs, out_static_libs, postfix_script, targets, tool_prefix, 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. Not all Makefiles will work equally well here, and some may require patching.Your Makefile must either support passing the install prefix using the PREFIX flag, or it needs to have a different way to pass install prefix to it. An equivalent of make install MUST be specified as one of the targets.This is because all the paths with param names prefixed by out_* are expressed as relative to INSTALLDIR, not the source directory.That is, if you execute only make, but not make install, this rule will not be able to pick up any build outputs. Finally, your make install rule must dereference symlinks to ensure that the installed files don't end up being symlinks to files in the sandbox. For example, installation lines like cp $SOURCE $DEST must become cp -L $SOURCE $DEST, as the -L will ensure that symlinks are dereferenced.

ATTRIBUTES

make_variant

make_variant(name, toolchain, kwargs)

Wrapper macro around the make() rule to force usage of the given make variant toolchain.

PARAMETERS

meson

A rule for building projects using the Ninja build tool

ninja

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

Rule for building external libraries with Ninja.

ATTRIBUTES

Rules Foreign CC

• boost_build
• cmake
• cmake_tool
• cmake_variant
• configure_make
• configure_make_variant
• ForeignCcArtifactInfo
• ForeignCcDepsInfo
• make
• make_tool
• make_variant
• meson
• meson_with_requirements
• native_tool_toolchain
• ninja
• ninja_tool
• rules_foreign_cc_dependencies
• ToolInfo

boost_build

boost_build(name, additional_inputs, additional_tools, alwayslink, bootstrap_options, build_data,
            copts, data, defines, deps, env, includes, lib_name, lib_source, linkopts, out_bin_dir,
            out_binaries, out_data_dirs, out_dll_dir, out_headers_only, out_include_dir,
            out_interface_libs, out_lib_dir, out_shared_libs, out_static_libs, postfix_script,
            tool_prefix, 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, build_data, cache_entries,
      copts, data, defines, deps, env, generate_args, generate_crosstool_file, includes, install,
      install_args, lib_name, lib_source, linkopts, out_bin_dir, out_binaries, out_data_dirs,
      out_dll_dir, out_headers_only, out_include_dir, out_interface_libs, out_lib_dir,
      out_shared_libs, out_static_libs, postfix_script, targets, tool_prefix, tools_deps,
      working_directory)

Rule for building external library with CMake.

ATTRIBUTES

configure_make

configure_make(name, additional_inputs, additional_tools, alwayslink, args, autoconf,
               autoconf_options, autogen, autogen_command, autogen_options, autoreconf,
               autoreconf_options, build_data, configure_command, configure_in_place,
               configure_options, configure_prefix, copts, data, defines, deps, env, includes,
               install_prefix, lib_name, lib_source, linkopts, out_bin_dir, out_binaries,
               out_data_dirs, out_dll_dir, out_headers_only, out_include_dir, out_interface_libs,
               out_lib_dir, out_shared_libs, out_static_libs, postfix_script, prefix_flag, targets,
               tool_prefix, 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, build_data, copts, data, defines,
     deps, env, includes, install_prefix, lib_name, lib_source, linkopts, out_bin_dir, out_binaries,
     out_data_dirs, out_dll_dir, out_headers_only, out_include_dir, out_interface_libs, out_lib_dir,
     out_shared_libs, out_static_libs, postfix_script, targets, tool_prefix, 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. Not all Makefiles will work equally well here, and some may require patching.Your Makefile must either support passing the install prefix using the PREFIX flag, or it needs to have a different way to pass install prefix to it. An equivalent of make install MUST be specified as one of the targets.This is because all the paths with param names prefixed by out_* are expressed as relative to INSTALLDIR, not the source directory.That is, if you execute only make, but not make install, this rule will not be able to pick up any build outputs. Finally, your make install rule must dereference symlinks to ensure that the installed files don't end up being symlinks to files in the sandbox. For example, installation lines like cp $SOURCE $DEST must become cp -L $SOURCE $DEST, as the -L will ensure that symlinks are dereferenced.

ATTRIBUTES

make_tool

make_tool(name, env, srcs)

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

ATTRIBUTES

meson

meson(name, additional_inputs, additional_tools, alwayslink, build_args, build_data, copts, data,
      defines, deps, env, includes, install, install_args, lib_name, lib_source, linkopts, options,
      out_bin_dir, out_binaries, out_data_dirs, out_dll_dir, out_headers_only, out_include_dir,
      out_interface_libs, out_lib_dir, out_shared_libs, out_static_libs, postfix_script, targets,
      tool_prefix, tools_deps)

Rule for building external libraries with Meson.

ATTRIBUTES

native_tool_toolchain

native_tool_toolchain(name, env, 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, build_data, copts, data, defines,
      deps, directory, env, includes, lib_name, lib_source, linkopts, out_bin_dir, out_binaries,
      out_data_dirs, out_dll_dir, out_headers_only, out_include_dir, out_interface_libs, out_lib_dir,
      out_shared_libs, out_static_libs, postfix_script, targets, tool_prefix, tools_deps)

Rule for building external libraries with Ninja.

ATTRIBUTES

ninja_tool

ninja_tool(name, env, srcs)

Rule for building Ninja. Invokes configure script.

ATTRIBUTES

ForeignCcArtifactInfo

ForeignCcArtifactInfo(bin_dir_name, dll_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(env, path, target)

Information about the native tool

FIELDS

cmake_tool

cmake_tool(name, srcs, kwargs)

PARAMETERS

cmake_variant

cmake_variant(name, toolchain, kwargs)

Wrapper macro around the cmake() rule to force usage of the given make variant toolchain.

PARAMETERS

configure_make_variant

configure_make_variant(name, toolchain, kwargs)

Wrapper macro around the configure_make() rule to force usage of the given make variant toolchain.

PARAMETERS

make_variant

make_variant(name, toolchain, kwargs)

Wrapper macro around the make() rule to force usage of the given make variant toolchain.

PARAMETERS

meson_with_requirements

meson_with_requirements(name, requirements, kwargs)

Wrapper macro around Meson rule to add Python libraries required by the Meson build.

PARAMETERS

rules_foreign_cc_dependencies

rules_foreign_cc_dependencies(native_tools_toolchains, register_default_tools, cmake_version,
                              make_version, ninja_version, meson_version, pkgconfig_version,
                              register_preinstalled_tools, register_built_tools, register_toolchains,
                              register_built_pkgconfig_toolchain)

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