diff --git a/.bazelci/config.yaml b/.bazelci/config.yaml index ff59e46..8567e95 100644 --- a/.bazelci/config.yaml +++ b/.bazelci/config.yaml @@ -138,6 +138,8 @@ tasks: working_directory: docs build_targets: - //... + run_targets: + - //:test_docs min_supported_version: name: "Minimum Supported Version" bazel: "3.7.0" diff --git a/.gitignore b/.gitignore index c89a196..4b2f484 100644 --- a/.gitignore +++ b/.gitignore @@ -71,6 +71,9 @@ fabric.properties # Vim swap files .*.sw? +# Bazel CI +bazelci.py + ##### # Bazel: https://github.com/github/gitignore/blob/master/community/Bazel.gitignore ##### diff --git a/README.md b/README.md index 1441b99..41ec0e5 100644 --- a/README.md +++ b/README.md @@ -25,11 +25,11 @@ For more generalized updates, please see [NEWS.md](./NEWS.md) or checkout the ## Building CMake projects -- Build libraries/binaries with CMake from sources using cmake_external rule -- Use cmake_external targets in [cc_library][ccl], [cc_binary][ccb] targets as dependency -- Bazel [cc_toolchain][cct] parameters are used inside cmake_external build -- See full list of cmake_external arguments below 'example' -- cmake_external is defined in `./tools/build_defs` +- 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:** @@ -38,7 +38,7 @@ For more generalized updates, please see [NEWS.md](./NEWS.md) or checkout the 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_external` 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 `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 @@ -105,7 +105,7 @@ bazel build //:pcre **Usage on Windows** -When using on Windows, you should start Bazel in MSYS2 shell, as the shell script inside cmake_external assumes this. +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. diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel index a5a37ac..abba723 100644 --- a/docs/BUILD.bazel +++ b/docs/BUILD.bazel @@ -34,8 +34,9 @@ genrule( outs = ["generate_docs.sh"], cmd = """cat << EOF > $@ #!/bin/bash -set -e +set -euo pipefail cat \\$${BUILD_WORKSPACE_DIRECTORY}/$(location //:docs) > \\$${BUILD_WORKSPACE_DIRECTORY}/README.md +EOF """, ) @@ -44,3 +45,8 @@ sh_binary( srcs = [":generate_docs_src"], data = [":docs"], ) + +sh_binary( + name = "test_docs", + srcs = ["test_docs.sh"] +) \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index c17ab1c..8880007 100644 --- a/docs/README.md +++ b/docs/README.md @@ -42,7 +42,7 @@ Rule for building Boost. Invokes bootstrap.sh and then b2 install. | data | Files needed by this rule at runtime. May list file or rule targets. Generally allows any target. | List of labels | optional | [] | | defines | Optional compilation definitions to be passed to the dependencies of this library. They are NOT passed to the compiler, you should duplicate them in the configuration options. | List of strings | optional | [] | | deps | Optional dependencies to be copied into the directory structure. Typically those directly required for the external building of the library/binaries. (i.e. those that the external buidl system will be looking for and paths to which are provided by the calling rule) | List of labels | optional | [] | -| env | Environment variables to set during the build. $(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported. | Dictionary: String -> String | optional | {} | +| env | Environment variables to set during the build. $(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported. | Dictionary: String -> String | optional | {} | | headers_only | __deprecated__: Use out_headers_only instead. | Boolean | optional | False | | interface_libraries | __deprecated__: Use out_interface_libs instead. | List of strings | optional | [] | | lib_name | Library name. Defines the name of the install directory and the name of the static library, if no output files parameters are defined (any of static_libraries, shared_libraries, interface_libraries, binaries_names) Optional. If not defined, defaults to the target's name. | String | optional | "" | @@ -94,7 +94,7 @@ Rule for building external library with CMake. | data | Files needed by this rule at runtime. May list file or rule targets. Generally allows any target. | List of labels | optional | [] | | defines | Optional compilation definitions to be passed to the dependencies of this library. They are NOT passed to the compiler, you should duplicate them in the configuration options. | List of strings | optional | [] | | deps | Optional dependencies to be copied into the directory structure. Typically those directly required for the external building of the library/binaries. (i.e. those that the external buidl system will be looking for and paths to which are provided by the calling rule) | List of labels | optional | [] | -| env | Environment variables to set during the build. $(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported. | Dictionary: String -> String | optional | {} | +| env | Environment variables to set during the build. $(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported. | Dictionary: String -> String | optional | {} | | env_vars | CMake environment variable values to join with toolchain-defined. For example, additional CXXFLAGS. | Dictionary: String -> String | optional | {} | | generate_args | Arguments for CMake's generate command. Arguments should be passed as key/value pairs. eg: ["-G Ninja", "--debug-output", "-DFOO=bar"]. Note that unless a generator (-G) argument is provided, the default generators are [Unix Makefiles](https://cmake.org/cmake/help/latest/generator/Unix%20Makefiles.html) for Linux and MacOS and [Ninja](https://cmake.org/cmake/help/latest/generator/Ninja.html) for Windows. | List of strings | optional | [] | | generate_crosstool_file | When True, CMake crosstool file will be generated from the toolchain values, provided cache-entries and env_vars (some values will still be passed as -Dkey=value and environment variables). If CMAKE_TOOLCHAIN_FILE cache entry is passed, specified crosstool file will be used When using this option to cross-compile, it is required to specify CMAKE_SYSTEM_NAME in the cache_entries | Boolean | optional | True | @@ -187,14 +187,14 @@ Rule for building external libraries with configure-make pattern. Some 'configur | data | Files needed by this rule at runtime. May list file or rule targets. Generally allows any target. | List of labels | optional | [] | | defines | Optional compilation definitions to be passed to the dependencies of this library. They are NOT passed to the compiler, you should duplicate them in the configuration options. | List of strings | optional | [] | | deps | Optional dependencies to be copied into the directory structure. Typically those directly required for the external building of the library/binaries. (i.e. those that the external buidl system will be looking for and paths to which are provided by the calling rule) | List of labels | optional | [] | -| env | Environment variables to set during the build. $(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported. | Dictionary: String -> String | optional | {} | +| env | Environment variables to set during the build. $(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported. | Dictionary: String -> String | optional | {} | | headers_only | __deprecated__: Use out_headers_only instead. | Boolean | optional | False | | install_prefix | Install prefix, i.e. relative path to where to install the result of the build. Passed to the 'configure' script with --prefix flag. | String | optional | "" | | interface_libraries | __deprecated__: Use out_interface_libs instead. | List of strings | optional | [] | | lib_name | Library name. Defines the name of the install directory and the name of the static library, if no output files parameters are defined (any of static_libraries, shared_libraries, interface_libraries, binaries_names) Optional. If not defined, defaults to the target's name. | String | optional | "" | | lib_source | Label with source code to build. Typically a filegroup for the source of remote repository. Mandatory. | Label | required | | | linkopts | Optional link options to be passed up to the dependencies of this library | List of strings | optional | [] | -| make_commands | Optinal make commands, defaults to ["make", "make install"] | List of strings | optional | ["make", "make install"] | +| make_commands | Optional make commands. | List of strings | optional | ["make", "make install"] | | out_bin_dir | Optional name of the output subdirectory with the binary files, defaults to 'bin'. | String | optional | "bin" | | out_binaries | Optional names of the resulting binaries. | List of strings | optional | [] | | out_headers_only | Flag variable to indicate that the library produces only headers | Boolean | optional | False | @@ -238,7 +238,7 @@ Rule for building external libraries with GNU Make. GNU Make commands (make and | data | Files needed by this rule at runtime. May list file or rule targets. Generally allows any target. | List of labels | optional | [] | | defines | Optional compilation definitions to be passed to the dependencies of this library. They are NOT passed to the compiler, you should duplicate them in the configuration options. | List of strings | optional | [] | | deps | Optional dependencies to be copied into the directory structure. Typically those directly required for the external building of the library/binaries. (i.e. those that the external buidl system will be looking for and paths to which are provided by the calling rule) | List of labels | optional | [] | -| env | Environment variables to set during the build. $(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported. | Dictionary: String -> String | optional | {} | +| env | Environment variables to set during the build. $(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported. | Dictionary: String -> String | optional | {} | | headers_only | __deprecated__: Use out_headers_only instead. | Boolean | optional | False | | interface_libraries | __deprecated__: Use out_interface_libs instead. | List of strings | optional | [] | | keep_going | __deprecated__: To maintain this behavior, pass -k to the args attribute when not using the make_commands attribute. | Boolean | optional | True | @@ -331,7 +331,7 @@ Rule for building external libraries with [Ninja](https://ninja-build.org/). | defines | Optional compilation definitions to be passed to the dependencies of this library. They are NOT passed to the compiler, you should duplicate them in the configuration options. | List of strings | optional | [] | | deps | Optional dependencies to be copied into the directory structure. Typically those directly required for the external building of the library/binaries. (i.e. those that the external buidl system will be looking for and paths to which are provided by the calling rule) | List of labels | optional | [] | | directory | A directory to pass as the -C argument. The rule will always use the root directory of the lib_sources attribute if this attribute is not set | String | optional | "" | -| env | Environment variables to set during the build. $(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported. | Dictionary: String -> String | optional | {} | +| env | Environment variables to set during the build. $(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, but unlike with other rules, these will be replaced with absolute paths to those files, because the build does not run in the exec root. No other macros are supported. | Dictionary: String -> String | optional | {} | | headers_only | __deprecated__: Use out_headers_only instead. | Boolean | optional | False | | interface_libraries | __deprecated__: Use out_interface_libs instead. | List of strings | optional | [] | | lib_name | Library name. Defines the name of the install directory and the name of the static library, if no output files parameters are defined (any of static_libraries, shared_libraries, interface_libraries, binaries_names) Optional. If not defined, defaults to the target's name. | String | optional | "" | diff --git a/docs/test_docs.sh b/docs/test_docs.sh new file mode 100755 index 0000000..c17eefd --- /dev/null +++ b/docs/test_docs.sh @@ -0,0 +1,12 @@ +#!/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 diff --git a/foreign_cc/private/framework.bzl b/foreign_cc/private/framework.bzl index 6082543..d5647e9 100644 --- a/foreign_cc/private/framework.bzl +++ b/foreign_cc/private/framework.bzl @@ -95,7 +95,7 @@ CC_EXTERNAL_RULE_ATTRIBUTES = { "env": attr.string_dict( doc = ( "Environment variables to set during the build. " + - "$(execpath) macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, " + + "`$(execpath)` macros may be used to point at files which are listed as data deps, tools_deps, or additional_tools, " + "but unlike with other rules, these will be replaced with absolute paths to those files, " + "because the build does not run in the exec root. " + "No other macros are supported." @@ -133,7 +133,7 @@ CC_EXTERNAL_RULE_ATTRIBUTES = { default = [], ), "make_commands": attr.string_list( - doc = "Optinal make commands, defaults to [\"make\", \"make install\"]", + doc = "Optional make commands.", mandatory = False, default = ["make", "make install"], ),