bazel
/
rules_foreign_cc
mirror of https://github.com/bazel-contrib/rules_foreign_cc
2
0
Fork 0
Code Issues Releases Activity

Updated documentation and removed the need to commit updated docs (#652)

This commit is contained in:
UebelAndre 2021-06-02 11:58:56 -07:00 committed by GitHub
parent 76198edc79
commit f471bbfeb2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 275 additions and 188 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
README.md
View File

@ -9,7 +9,7 @@ This is **not an officially supported Google product**
## Documentation
Documentation for all rules and providers are available [here](./docs/README.md)
Documentation for all rules and providers are available [here](https://docs.aspect.dev/rules_foreign_cc/)
## Bazel versions compatibility
@ -23,130 +23,6 @@ in future changes as these older versions are not tested.
For more generalized updates, please see [NEWS.md](./NEWS.md) or checkout the
[release notes](https://github.com/bazelbuild/rules_foreign_cc/releases) of current or previous releases
## Building CMake projects
- Build libraries/binaries with CMake from sources using cmake rule
- Use cmake targets in [cc_library][ccl], [cc_binary][ccb] targets as dependency
- Bazel [cc_toolchain][cct] 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][ccl], which can then be used in a C++ rule ([cc_binary][ccb] in this case).
In `WORKSPACE.bazel`, put
```python
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:
```python
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:
```bash
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.
```python
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"],
)
```
## Design document
[External C/C++ libraries rules](https://docs.google.com/document/d/1Gv452Vtki8edo_Dj9VTNJt5DA_lKTcSMwrwjJOkLaoU/edit?usp=sharing)

1
docs/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
*.md

79
docs/BUILD.bazel
View File

@ -1,5 +1,4 @@
load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
load("@bazel_skylib//rules:write_file.bzl", "write_file")
load("@bazel_skylib//rules:build_test.bzl", "build_test")
load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
genrule(
@ -14,33 +13,77 @@ genrule(
)
stardoc(
name = "docs",
out = "docs.md",
name = "flatten_docs",
out = "flatten.md",
header_template = ":flatten_header_vm",
input = "docs.bzl",
deps = ["@rules_foreign_cc//:bzl_srcs"],
)
# When this test fails, run
# (cd docs; bazel run :generate_docs)
diff_test(
name = "test",
file1 = ":docs",
file2 = "README.md",
stardoc(
name = "cmake_docs",
out = "cmake.md",
header_template = "common_header.vm",
input = "@rules_foreign_cc//foreign_cc:cmake.bzl",
deps = ["@rules_foreign_cc//:bzl_srcs"],
)
write_file(
stardoc(
name = "make_docs",
out = "make.md",
header_template = "common_header.vm",
input = "@rules_foreign_cc//foreign_cc:make.bzl",
deps = ["@rules_foreign_cc//:bzl_srcs"],
)
stardoc(
name = "ninja_docs",
out = "ninja.md",
header_template = "common_header.vm",
input = "@rules_foreign_cc//foreign_cc:ninja.bzl",
deps = ["@rules_foreign_cc//:bzl_srcs"],
)
stardoc(
name = "configure_make_docs",
out = "configure_make.md",
header_template = "common_header.vm",
input = "@rules_foreign_cc//foreign_cc:configure.bzl",
deps = ["@rules_foreign_cc//:bzl_srcs"],
)
DOCS_TARGETS = [
":flatten_docs",
":cmake_docs",
":ninja_docs",
":make_docs",
":configure_make_docs",
]
build_test(
name = "docs_build_test",
targets = DOCS_TARGETS,
visibility = ["//visibility:public"],
)
genrule(
name = "generate_docs_src",
out = "update.sh",
content = [
"#!/usr/bin/env bash",
"cd $BUILD_WORKSPACE_DIRECTORY",
"cp -fv bazel-bin/docs.md README.md",
],
srcs = DOCS_TARGETS,
outs = ["generate_docs.sh"],
cmd = """cat << EOF > $@
#!/bin/bash
set -euo pipefail
cat \\$${BUILD_WORKSPACE_DIRECTORY}/$(location //:flatten_docs) > \\$${BUILD_WORKSPACE_DIRECTORY}/flatten.md
cat \\$${BUILD_WORKSPACE_DIRECTORY}/$(location //:cmake_docs) > \\$${BUILD_WORKSPACE_DIRECTORY}/cmake.md
cat \\$${BUILD_WORKSPACE_DIRECTORY}/$(location //:ninja_docs) > \\$${BUILD_WORKSPACE_DIRECTORY}/ninja.md
cat \\$${BUILD_WORKSPACE_DIRECTORY}/$(location //:make_docs) > \\$${BUILD_WORKSPACE_DIRECTORY}/make.md
cat \\$${BUILD_WORKSPACE_DIRECTORY}/$(location //:configure_make_docs) > \\$${BUILD_WORKSPACE_DIRECTORY}/configure_make.md
EOF
""",
)
sh_binary(
name = "generate_docs",
srcs = [":generate_docs_src"],
data = [":docs"],
data = DOCS_TARGETS,
)

51
docs/README.md
View File

@ -1,23 +1,18 @@
<!-- Generated with Stardoc, Do Not Edit! -->
# Rules Foreign CC
<!-- Generated with Stardoc: http://skydoc.bazel.build -->
<!-- The comment above prevents this file from being rendered at https://docs.aspect.dev/ -->
<!-- But this file is not generated by stardoc -->
# Rules ForeignCc Docs
- [boost_build](#boost_build)
- [cmake](#cmake)
- [cmake_tool](#cmake_tool)
- [configure_make](#configure_make)
- [ForeignCcArtifact](#ForeignCcArtifact)
- [ForeignCcDeps](#ForeignCcDeps)
- [make](#make)
- [make_tool](#make_tool)
- [native_tool_toolchain](#native_tool_toolchain)
- [ninja](#ninja)
- [ninja_tool](#ninja_tool)
- [rules_foreign_cc_dependencies](#rules_foreign_cc_dependencies)
- [ToolInfo](#ToolInfo)
Documentation can be found at: https://docs.aspect.dev/rules_foreign_cc/
## Legacy documentation
The sections below exist to maintain links to the previous build rules. Again, the link above
should be used instead.
<a id="#boost_build"></a>
## boost_build
### boost_build
<pre>
boost_build(<a href="#boost_build-name">name</a>, <a href="#boost_build-additional_inputs">additional_inputs</a>, <a href="#boost_build-additional_tools">additional_tools</a>, <a href="#boost_build-alwayslink">alwayslink</a>, <a href="#boost_build-bootstrap_options">bootstrap_options</a>, <a href="#boost_build-data">data</a>, <a href="#boost_build-defines">defines</a>,
@ -60,7 +55,7 @@ Rule for building Boost. Invokes bootstrap.sh and then b2 install.
<a id="#cmake"></a>
## cmake
### cmake
<pre>
cmake(<a href="#cmake-name">name</a>, <a href="#cmake-additional_inputs">additional_inputs</a>, <a href="#cmake-additional_tools">additional_tools</a>, <a href="#cmake-alwayslink">alwayslink</a>, <a href="#cmake-build_args">build_args</a>, <a href="#cmake-cache_entries">cache_entries</a>, <a href="#cmake-data">data</a>,
@ -111,7 +106,7 @@ Rule for building external library with CMake.
<a id="#cmake_tool"></a>
## cmake_tool
### cmake_tool
<pre>
cmake_tool(<a href="#cmake_tool-name">name</a>, <a href="#cmake_tool-srcs">srcs</a>)
@ -130,7 +125,7 @@ Rule for building CMake. Invokes bootstrap script and make install.
<a id="#configure_make"></a>
## configure_make
### configure_make
<pre>
configure_make(<a href="#configure_make-name">name</a>, <a href="#configure_make-additional_inputs">additional_inputs</a>, <a href="#configure_make-additional_tools">additional_tools</a>, <a href="#configure_make-alwayslink">alwayslink</a>, <a href="#configure_make-args">args</a>, <a href="#configure_make-autoconf">autoconf</a>,
@ -192,7 +187,7 @@ Rule for building external libraries with configure-make pattern. Some 'configur
<a id="#make"></a>
## make
### make
<pre>
make(<a href="#make-name">name</a>, <a href="#make-additional_inputs">additional_inputs</a>, <a href="#make-additional_tools">additional_tools</a>, <a href="#make-alwayslink">alwayslink</a>, <a href="#make-args">args</a>, <a href="#make-data">data</a>, <a href="#make-defines">defines</a>, <a href="#make-deps">deps</a>, <a href="#make-env">env</a>,
@ -254,7 +249,7 @@ Rule for building Make. Invokes configure script and make install.
<a id="#native_tool_toolchain"></a>
## native_tool_toolchain
### native_tool_toolchain
<pre>
native_tool_toolchain(<a href="#native_tool_toolchain-name">name</a>, <a href="#native_tool_toolchain-path">path</a>, <a href="#native_tool_toolchain-target">target</a>)
@ -274,7 +269,7 @@ Rule for defining the toolchain data of the native tools (cmake, ninja), to be u
<a id="#ninja"></a>
## ninja
### ninja
<pre>
ninja(<a href="#ninja-name">name</a>, <a href="#ninja-additional_inputs">additional_inputs</a>, <a href="#ninja-additional_tools">additional_tools</a>, <a href="#ninja-alwayslink">alwayslink</a>, <a href="#ninja-args">args</a>, <a href="#ninja-data">data</a>, <a href="#ninja-defines">defines</a>, <a href="#ninja-deps">deps</a>, <a href="#ninja-directory">directory</a>,
@ -318,7 +313,7 @@ Rule for building external libraries with [Ninja](https://ninja-build.org/).
<a id="#ninja_tool"></a>
## ninja_tool
### ninja_tool
<pre>
ninja_tool(<a href="#ninja_tool-name">name</a>, <a href="#ninja_tool-srcs">srcs</a>)
@ -337,7 +332,7 @@ Rule for building Ninja. Invokes configure script.
<a id="#ForeignCcArtifact"></a>
## ForeignCcArtifact
### ForeignCcArtifact
<pre>
ForeignCcArtifact(<a href="#ForeignCcArtifact-bin_dir_name">bin_dir_name</a>, <a href="#ForeignCcArtifact-gen_dir">gen_dir</a>, <a href="#ForeignCcArtifact-include_dir_name">include_dir_name</a>, <a href="#ForeignCcArtifact-lib_dir_name">lib_dir_name</a>)
@ -364,7 +359,7 @@ Instances of ForeignCcArtifact are incapsulated in a depset ForeignCcDeps#artifa
<a id="#ForeignCcDeps"></a>
## ForeignCcDeps
### ForeignCcDeps
<pre>
ForeignCcDeps(<a href="#ForeignCcDeps-artifacts">artifacts</a>)
@ -382,7 +377,7 @@ Provider to pass transitive information about external libraries.
<a id="#ToolInfo"></a>
## ToolInfo
### ToolInfo
<pre>
ToolInfo(<a href="#ToolInfo-path">path</a>, <a href="#ToolInfo-target">target</a>)
@ -401,7 +396,7 @@ Information about the native tool
<a id="#rules_foreign_cc_dependencies"></a>
## rules_foreign_cc_dependencies
### rules_foreign_cc_dependencies
<pre>
rules_foreign_cc_dependencies(<a href="#rules_foreign_cc_dependencies-native_tools_toolchains">native_tools_toolchains</a>, <a href="#rules_foreign_cc_dependencies-register_default_tools">register_default_tools</a>, <a href="#rules_foreign_cc_dependencies-cmake_version">cmake_version</a>,
@ -423,5 +418,3 @@ Call this function from the WORKSPACE file to initialize rules_foreign_cc de
| <a id="rules_foreign_cc_dependencies-ninja_version"></a>ninja_version | The target version of the ninja toolchain if <code>register_default_tools</code> or <code>register_built_tools</code> is set to <code>True</code>. | <code>"1.10.2"</code> |
| <a id="rules_foreign_cc_dependencies-register_preinstalled_tools"></a>register_preinstalled_tools | If true, toolchains will be registered for the native built tools installed on the exec host | <code>True</code> |
| <a id="rules_foreign_cc_dependencies-register_built_tools"></a>register_built_tools | If true, toolchains that build the tools from source are registered | <code>True</code> |

3
docs/common_header.vm Normal file
View File

@ -0,0 +1,3 @@
<!-- Generated with Stardoc: http://skydoc.bazel.build -->
${moduleDocstring}

46
docs/index.md Normal file
View File

@ -0,0 +1,46 @@
# 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][cc]
rules.
[cc]: https://docs.bazel.build/versions/master/be/c-cpp.html
## Setup
To use the ForeignCc build rules, add the following content to your WORKSPACE file:
```python
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
name = "rules_foreign_cc",
sha256 = "d54742ffbdc6924f222d2179f0e10e911c5c659c4ae74158e9fe827aad862ac6",
strip_prefix = "rules_foreign_cc-0.2.0",
url = "https://github.com/bazelbuild/rules_foreign_cc/archive/0.2.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](./flatten.md#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](./cmake.md)
- [configure_make](./configure_make.md)
- [make](./make.md)
- [ninja](./ninja.md)
For additional rules/macros/providers, see the [full API in one page](./flatten.md).

12
docs/test_docs.sh
View File

@ -1,12 +0,0 @@
#!/bin/bash
set -euo pipefail
pushd "${BUILD_WORKSPACE_DIRECTORY}" &> /dev/null
bazel run //:generate_docs
if [ -n "$(git status --porcelain)" ]; then
git status
echo '/docs is out of date. Please run `bazel run //:generate_docs` from that directory and commit the results' >&2
exit 1
fi
popd &> /dev/null

5
foreign_cc/BUILD.bazel
View File

@ -1,5 +1,10 @@
load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
exports_files(
glob(["*.bzl"]),
visibility = ["//visibility:public"],
)
bzl_library(
name = "bzl_srcs",
srcs = glob(["**/*.bzl"]),

130
foreign_cc/cmake.bzl
View File

@ -1,4 +1,132 @@
""" Defines the rule for building external library with CMake
"""# CMake
## Building CMake projects
- Build libraries/binaries with CMake from sources using cmake rule
- Use cmake targets in [cc_library][ccl], [cc_binary][ccb] targets as dependency
- Bazel [cc_toolchain][cct] 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][ccl], which can then be used in a C++ rule ([cc_binary][ccb] in this case).
In `WORKSPACE.bazel`, put
```python
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:
```python
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:
```bash
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.
```python
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"],
)
```
[ccb]: https://docs.bazel.build/versions/master/be/c-cpp.html#cc_binary
[ccl]: https://docs.bazel.build/versions/master/be/c-cpp.html#cc_library
[cct]: https://docs.bazel.build/versions/master/be/c-cpp.html#cc_toolchain
"""
load(

5
foreign_cc/configure.bzl
View File

@ -1,4 +1,7 @@
# buildifier: disable=module-docstring
"""A rule for building projects using the[Configure+Make][cm] build tool
[cm]: https://www.gnu.org/prep/standards/html_node/Configuration.html
"""
load(
"//foreign_cc/private:cc_toolchain_util.bzl",
"get_flags_info",

3
foreign_cc/make.bzl
View File

@ -1,4 +1,5 @@
# buildifier: disable=module-docstring
"""A rule for building projects using the [GNU Make](https://www.gnu.org/software/make/) build tool"""
load(
"//foreign_cc/private:cc_toolchain_util.bzl",
"get_flags_info",

2
foreign_cc/ninja.bzl
View File

@ -1,4 +1,4 @@
"""A module defining the `ninja` rule. A rule for building projects using the Ninja build tool"""
"""A rule for building projects using the [Ninja](https://ninja-build.org/) build tool"""
load(
"//foreign_cc/private:detect_root.bzl",