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 a bazel debug message or the latest
    #       release on the releases page: https://github.com/bazel-contrib/rules_foreign_cc/releases
    #
    # integrity = "...",
    strip_prefix = "rules_foreign_cc-{release_archive}",
    url = "https://github.com/bazel-contrib/rules_foreign_cc/archive/{release_archive}.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/bazel-contrib/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/bazel-contrib/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

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

cmake(name, deps, data, additional_inputs, additional_tools, alwayslink, build_args, build_data,
      cache_entries, copts, defines, dynamic_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, set_file_prefix_map, targets, tool_prefix,
      tools_deps, working_directory)

Rule for building external library with CMake.

ATTRIBUTES

cmake_variant

load("@rules_foreign_cc//foreign_cc:cmake.bzl", "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

load("@rules_foreign_cc//foreign_cc:configure.bzl", "configure_make")

configure_make(name, deps, data, 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, configure_xcompile, copts, defines, dynamic_deps,
               env, executable_ldflags_vars, 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, set_file_prefix_map, shared_ldflags_vars, 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

load("@rules_foreign_cc//foreign_cc:configure.bzl", "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

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

make(name, deps, data, additional_inputs, additional_tools, alwayslink, args, build_data, copts,
     defines, dynamic_deps, env, executable_ldflags_vars, 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, set_file_prefix_map, shared_ldflags_vars, 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

load("@rules_foreign_cc//foreign_cc:make.bzl", "make_variant")

make_variant(name, toolchain, kwargs)

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

PARAMETERS

A rule for building projects using the Meson build system

meson

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

meson(name, deps, data, additional_inputs, additional_tools, alwayslink, build_args, build_data,
      copts, defines, dynamic_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, set_file_prefix_map, setup_args, targets, tool_prefix, tools_deps)

Rule for building external libraries with Meson.

ATTRIBUTES

meson_with_requirements

load("@rules_foreign_cc//foreign_cc:meson.bzl", "meson_with_requirements")

meson_with_requirements(name, requirements, kwargs)

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

PARAMETERS

A rule for building projects using the Ninja build tool

ninja

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

ninja(name, deps, data, additional_inputs, additional_tools, alwayslink, args, build_data, copts,
      defines, directory, dynamic_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, set_file_prefix_map, targets,
      tool_prefix, tools_deps)

Rule for building external libraries with Ninja.

ATTRIBUTES