Add Skylark Remote Repositories design docs to the website.
The original docs are at
bazel init (removed doc)
Skylark Remote Repositories: https://docs.google.com/document/d/1jKbNXOVp2T1zJD_iRnVr8k5D0xZKgO8blMVDlXOksJg/
Generating C++ crosstool with a Skylark Remote Repository: https://docs.google.com/document/d/1Ju74cmBCfYl8SEZT_tXhRmbi49ZLMzXgoQzzqve-dxI
--
Change-Id: I5acb28c08c0de552c259e091249e8787c2cf0e58
Reviewed-on: https://bazel-review.googlesource.com/4222
MOS_MIGRATED_REVID=129078523
diff --git a/site/designs/_posts/2015-03-06-bazel-init.md b/site/designs/_posts/2015-03-06-bazel-init.md
new file mode 100644
index 0000000..faf0c09
--- /dev/null
+++ b/site/designs/_posts/2015-03-06-bazel-init.md
@@ -0,0 +1,298 @@
+---
+layout: contribute
+title: bazel init a.k.a ./configure for Bazel
+---
+
+__This design document has be replaced by
+[Skylark Remote Repositories](/designs/2015/07/02/skylark-remote-repositories.html)
+and is maintained here just for reference__
+
+# bazel init a.k.a ./configure for Bazel
+_A configuration mechanism for Bazel_
+
+__Status:__ deprecated, replaced by [Skylark Remote Repositories](/designs/2015/07/02/skylark-remote-repositories.html)
+
+__Author:__ dmarting@google.com
+
+## I. Rationale
+
+Bazel tooling needs special setup to work. For example, C++ crosstool
+configuration requires path to GCC or Java configuration requires the
+path to the JDK. Autodetecting those paths from Bazel would be broken
+because each ruleset requires its own configuration (C++ CROSSTOOL
+information is totally different from JDK detection or from go root
+detection). Therefore, providing a general mechanism to configure
+Bazel tooling seems natural. To have Bazel self-contained, we will
+ship this mechanism as an additional command of Bazel. Because this
+command deals with non-hermetic parts of Bazel, this command should
+also group all non-hermetic steps (i.e. it should fetch the
+dependencies from the remote repositories) so a user can run it and
+get on a plane with everything needed.
+
+## II. Considered use-cases
+
+We consider the 3 following use-cases:
+
+ - __UC1.__ The user wants to not worry about tools configuration and
+ use the default one for golden languages (Java, C++, Shell) and
+ wants to also activate an optional language (Go). No configuration
+ information (aka `tools` package) should be checked into the
+ version control system.
+ - __UC2.__ The user wants to tweak Java configuration but not C++. Of
+ course, the user wants his tweak to be shared with his team (i.e.
+ `tools/jdk` should be checked into the version control system).
+ However, the user does not want to have C++ information (i.e.
+ `tools/cpp`) in the VCS.
+ - __UC3.__ The user wants his build to be hermetic and he wants to
+ set up everything in his `tools` directory (Google use-case).
+
+### Notes
+
+This document addresses the special case of the configuration of the
+`tools` package, mechanisms presented here could be extended to any
+dependency that needs to be configured (e.g., detecting the installed
+libncurse) but that is out of the scope of this document.
+
+Anywhere in this document we refer to the `tools` package as the
+package that will receive the current `tools` package content, it does
+not commit to keep that package name.
+
+## III. Requirements
+
+### `bazel init` should:
+ - _a1._ Not be available in hermetic version (i.e. Google version of
+ Bazel, a.k.a Blaze).
+ - _a2._ Allow per-language configuration. I.e., Java and C++ tooling
+ configuration should be separated.
+ - _a3._ Allow Skylark add-ons to specify their configuration, this
+ should be pluggable so we can actually activate configuration per
+ rule set.
+ - _a4._ Support at least 3 modes corresponding to each envisioned
+ use-cases:
+ * __UC1.__: __installed__ (default mode): a "hidden" `tools`
+ package contains the detected tool paths (`gcc`, the JDKs, ...)
+ as well as their configuration (basically the content of the
+ current `//tools` package). This package should be constructed
+ as much as possibly automatically with a way for the user to
+ overwrite detected settings.
+ * __UC2.__: __semi-hermetic__: the "hidden" `tools` package is used
+ only for linking the actual tool paths but the configuration
+ would be checked-in into the workspace (in a similar way that
+ what is currently done in Bazel). The "hidden" `tools` package
+ could contains several versions of the same tools (e.g., jdk-8,
+ jdk-7, ...) and the workspace link to a specific one.
+ * __UC3.__: __hermetic__: this is the Google way of thing: the
+ user check-in everything that he thinks belong to the workspace
+ and the init command should do nothing.
+ - _a5._ Support explicit reconfiguration. If the configuration
+ mechanism changes or the user wants to tune the configuration, it
+ should support to modify the configuration, i.e., update the
+ various paths or change the default options.
+
+### `bazel init` could:
+
+ - _b1._: Initialize a new workspace: as it would support configuring
+ a whole tool directory, it might be quite close to actually
+ initializing a new workspace.
+
+## IV. User interface
+
+To be efficient, when the `tools` directory is missing, `bazel build`
+should display an informative error message to actually run `bazel
+init`.
+
+Configuration is basically just setting a list of build constants like
+the path to the JDK, the list of C++ flags, etc...
+
+When the user type `bazel init`, the configuration process starts with
+the default configuration (e.g., configure for “gold features” such as
+C++, Java, sh_, ...). It should try to autodetect as much as possible.
+If a language configuration needs something it cannot autodetect, then
+it can prompt the user for the missing information and the
+configuration can fail if something is really wrong.
+
+On default installation, `bazel init` should not prompt the user at
+all. When the process finishes, the command should output a summary of
+the configuration. The configuration is then stored in a "hidden"
+directory which is similar to our current `tools` package. By default,
+the labels in the configuration would direct to that package (always
+mapped as a top-level package). The "hidden:" directory would live in
+`$(output_base)/init/tools` and be mapped using the package path
+mechanism. The `--overwrite` option would be needed to rerun the
+automatic detection and overwrite everything including the eventual
+user-set options.
+
+For the hermetic mode, the user has to recreate the default tools
+package inside the workspace. If the user has a package with the same
+name in the workspace, then the "hidden" directory should be ignored
+(--package_path).
+
+To set a configuration option, the user would type `bazel init
+java:jdk=/path/to/jdk` or to use the autodetection on a specific
+option `bazel init java:jdk`. The list of settings group could be
+obtained by `bazel init list` and the list of option with their value
+for a specific language by `bazel init list group`. `bazel init list
+all` could give the full configuration of all activated groups.
+
+_Prospective idea:_ Bazel init should explore the BUILD file to find the
+Skylark `load` statements, determine if there is an associated init
+script and use it.
+
+## V. Developer interface
+
+This section presents the support for developer that wants to add
+autoconfiguration for a ruleset. The developer adding a configuration
+would provide with a configuration script for it. This script will be
+in charge of creating the package in the tools directory during `bazel
+init` (i.e., the script for Java support will construct the
+//tools/jdk package in the "hidden" package path).
+
+Because of skylark rules and the fact that the configuration script
+should run before having access to the C++ and Java tooling, this
+seems unreasonable to use a compiled language (Java or C++) for this
+script. We could use the Skylark support to make it a subset of python
+or we could use a bash script. Python support would be portable since
+provided by Bazel itself and consistent with skylark. It also gives
+immediate support for manipulating BUILD files. So keeping a
+"skylark-like" syntax, the interface would look like:
+
+```python
+configuration(
+ name, # name of the tools package to configure
+ autodetect_method, # the auto detection method
+ generate_method, # the actual package generation
+ load_method, # A method to load the attributes presented
+ # to the user from the package
+ attrs = { # List of attributes this script propose
+ "jdk_path": String,
+ "__some_other_path": String, # not user-settable
+ "jdk_version": Integer,
+ })
+```
+
+Given that interface, an initial run of `bazel init` would do:
+
+ 1. Find all language configuration scripts
+ 2. Run `load_method` for each script
+ 3. Run `autodetect_method` for each script. Replace non loaded
+ attribute (attribute still undefined after `load_method`) if and
+ only if `--rerun` option is provided
+ 4. Run `generate_method` for each script
+ 5. Fetch all non up to date dependencies of remote repository
+
+See Appendix B for examples of such methods.
+
+## VI. Implementation plan
+
+ 1. Add the hidden tools directory and have it binded with package
+ path when no tools directory exists. The hidden tools directory
+ will have a WORKSPACE file and will have an automatic local
+ repository with the "init" name so that we can actually bind
+ targets from it into our workspace.
+ 2. Add `bazel init` that support the configuration for native
+ packages in Java, that is: Java, C++, genrule and test. This
+ would create the necessary mechanisms for supporting the
+ developer and the basic user interface. This commands will be
+ totally in Java for now and should trigger the fetch part of the
+ remote repository.
+ 3. Design and implement the language extension ala Skylark using the
+ design for the Java version of point 2.
+ 4. Convert the existing configuration into that language.
+ 5. Integrate the configuration with Skylark (i.e. Skylark rules
+ writer can add configuration step). We should here decide on
+ how it should be included (as a separate script? how do we
+ ship a skylark rule set? can we have load statement loading
+ a full set of rules?).
+ 6. Create configuration for the existing skylark build rules. If
+ we support load statement with label, we can then create a
+ repository for Skylark rules.
+
+## Appendix A. Various comments
+
+ 1. We should get rid of the requirement for a `tools/defaults/BUILD` file.
+ 2. To works correctly, we need some local caching of the bazel
+ repository so tools are available. We could have bazelrc specify a
+ global path to the local cache (with `/etc/bazel.bazelrc` being loaded
+ first to `~/.bazelrc`). We could use a `~/.bazel` directory to put an
+ updatable tools cache also. This is needed because user probably want
+ to initialize a workspace tooling on a plane
+ 3. This proposal would probably add a new top-level package. We
+ should really take care of the naming convention for default top
+ packages (i.e., `tools`, `tools/defaults`, `visibility`, `external`,
+ `condition`...). We are going to make some user unhappy if they cannot
+ have an `external` directory at the top of their workspace (I would
+ just not use a build system that goes against my workspace structure).
+ While it is still time to do it, we should rename them with a nice
+ naming convention. A good way to do it is to make top-package name
+ constants, possibly settable in the WORKSPACE file (so we can actually
+ keep the name we like but user that are bothered by that can change
+ it).
+ 4. As we will remove the tools directory from the workspace, it
+ makes sense to add another prelude_bazel file somewhere else. As the
+ `WORKSPACE` file controls the workspace, it makes sense to have the
+ `prelude_bazel` logic in it (and the load statement should support
+ labels so that a user can actually specify remote repository labels).
+
+## Appendix B. Skylark-like code examples of configuration functions
+
+This is just a quick draft, please feel free to propose improvements:
+
+```python
+# env is the environment, attrs are the values set either from the command-line
+# or from loading the package
+def autodetect_method(env, attrs):
+ if not attrs.java_version: # If not given in the command line nor loaded
+ attrs.java_version = 8
+ if not attrs.jdk_path:
+ if env.has("JDK_HOME"):
+ attrs.jdk_path = env.get("JDK_HOME")
+ elif env.os = "darwin":
+ attrs.jdk_path = system("/usr/libexec/java_home -v 1." + attrs.java_version + "+")
+ else:
+ attrs.jdk_path = basename(basename(readlink(env.path.find(java))))
+ if not attrs.jdk_path:
+ fail("Could not find JDK home, please set it with `bazel init java:jdk_path=/path/to/jdk`")
+ attrs.__some_other_path = first(glob(["/usr/bin/java", "/usr/local/bin/java"]))
+
+
+# attrs is the list of attributes. It basically contains the list of rules
+# we should generate in the corresponding package. Please note
+# That all labels are replaced by relative ones as it should not be able
+# to write out of the package.
+def generate_method(attrs):
+ scratch_file("BUILD.jdk", """
+Content of the jdk BUILD file.
+""")
+ # Create binding using local_repository. This should not lie in
+ # the WORKSPACE file but in a separate WORKSPACE file in the hidden
+ # directory.
+ local_repository(name = "jdk", path = attrs.jdk_path, build_file = "BUILD.jdk")
+ bind("@jdk//jdk", "jdk") # also add a filegroup("jdk", "//external:jdk")
+ java_toolchain(name = "toolchain", source = attrs.java_version, target = attrs.java_version)
+ # The magic __BAZEL_*__ variable could be set so we don’t
+ # redownload the repository if possible. This install_target
+ # should leverage the work already done on remote repositories.
+ # This should build and copy the result into the tools directory with
+ # The corresponding exports_files now.
+ install_target(__BAZEL_REPOSITORY__, __BAZEL_VERSION__, "//src/java_tools/buildjar:JavaBuilder_deploy.jar")
+ install_target(__BAZEL_REPOSITORY__, __BAZEL_VERSION__, "//src/java_tools/buildjar:JavaBuilder_deploy.jar")
+ copy("https://ijar_url", "ijar")
+
+
+
+# Load the package attributes.
+# - attrs should be written and value will be replaced by the user-provided
+# one if any
+# - query is a query object restricted to the target package and resolving label
+# relatively to the target package. This object should also be able to search
+# for repository binding
+# Note that the query will resolve in the actual tools directory, not the hidden
+# one if it exists whereas the generation only happens in the hidden one.
+def load_method(attrs, query):
+ java_toolchain = query.getOne(kind("java_toolchain", "..."))
+ if java_toolchain:
+ attrs.jdk_version = max(java_toolchain.source, java_toolchain.target)
+ jdk = query.getOne(attr("name", "jdk", kind("local_repository", "...")))
+ if jdk:
+ attrs.jdk_path = jdk.path
+```
diff --git a/site/designs/_posts/2015-07-02-skylark-remote-repositories.md b/site/designs/_posts/2015-07-02-skylark-remote-repositories.md
new file mode 100644
index 0000000..96e5fe0
--- /dev/null
+++ b/site/designs/_posts/2015-07-02-skylark-remote-repositories.md
@@ -0,0 +1,161 @@
+---
+layout: contribute
+title: Skylark Remote Repositories
+---
+
+# Skylark Remote Repositories
+
+__Status:__ implemented
+
+__Author:__ dmarting@google.com
+
+__Reviewers:__ lberki@google.com, laurentlb@google.com, kchodorow@google.com
+
+## Context
+
+[Skylark](/docs/skylark/index.html) is the
+extension language for Bazel and lets Bazel users describe the
+build for new languages easily. External users do not create
+native rules and we want to avoid them doing so.
+
+[Remote repositories](/docs/external.html)
+are a convenient way to specify your third party dependencies
+and to fetch them along with the build if you don’t want to
+check them in your repository.
+
+This document discuss “Skylark Remote Repositories”, that is
+creating new remote repository rules using Skylark.
+
+## Why?
+
+ - Enable users to specify new kind of repositories, we already have
+ requests for PyPI for example. We don’t want to be supporting every
+ kind of repository that exists outside.
+ - Enable Skylark rules to write macros to have one-liners for
+ including all their tools in your WORKSPACE file.
+ - Enable configuration of languages tooling:
+ [bazel init](/design/2015/03/06/bazel-init.html)
+ first approach as a separate tools is not really user-friendly and
+ the same kind of flexibility can be achieved by creating
+ repositories rule in Skylark. An example for the JDK is
+ [here](https://github.com/damienmg/bazel/commit/c40bd9c71965f0a8c85b732a0b0c3dbe31e017cf/jdk.bzl).
+
+## User interface (see the [JDK example](https://github.com/damienmg/bazel/commit/c40bd9c71965f0a8c85b732a0b0c3dbe31e017cf/jdk.bzl))
+
+The load statement will now be available from the WORKSPACE, working
+the same way it does for build file but with WORKSPACE specific
+functions instead.
+
+In the same way that we have macros and rules for the BUILD file, we
+are going to have macros and rule for the WORKSPACE file. The former
+will be a convenient way to combine remote repositories and the latter
+enable creation of new repositories kind.
+
+### Macros
+
+Skylark macros would be activated in the WORKSPACE file and would
+behave as expected. Macros would enable to combine remote repositories
+creation and bind into a single rules E.g. `setup_java()` would set-up
+all bindings and the local repository needed to build java target:
+
+```python
+def setup_java():
+ native.new_local_repository(name = “jdk-local”, path = “/usr/share/java/jdk8”, build_file = “jdk.BUILD”)
+ for target in ["jni_header", "jni_md_header", "langtools", "bootclasspath", "extdir", "toolchain", "jdk", "java", "javac", "jar"]:
+ native.bind(name=target, actual="@%s//:%s" % (name, target))
+ native.bind(name="jni_md_header-linux", actual="@%s//:jni_md_header" % name)
+ native.bind(name="jni_md_header-darwin", actual="@%s//:jni_md_header" % name)
+```
+
+### Remote repository rule
+A remote repository rule would be set-up the same way we set-up a
+build rule but with the `repository_rule` statement:
+
+```python
+jdk_repository = repository_rule(
+ implementation = my_impl,
+ attrs = {
+ “java_home”: attr.string(mandatory=False),
+ “java_version”: attr.string(default=“1.8”),
+ }
+```
+
+This statement takes only 2 arguments: an implementation function and
+a list of attributes. The syntax is similar to the rule statement but
+attributes can only takes primitive type (String, Label, Integer,
+Boolean, …) and not artifacts.
+
+The implementation function takes exactly one argument: the repository
+context. This context will provides many convenience methods for doing
+non hermetic operations, e.g., :
+
+- For discovering the environment:
+ * access system environment (`ctxt.os`),
+ * execute a program and get the standard output (`ctxt.execute`) to
+ discover the environment,
+ * …
+- For creating the remote repository:
+ * fetch an artifact from URL (`ctxt.download`),
+ * uncompress an artifact (`ctxt.path(...).uncompress(outputPath)`),
+ * “copy” a directory from the system (`ctx.fetch_path(...)`),
+ * create a build file (`ctxt.build_file(...)`)
+ * ...
+
+The precise list of methods the repository context will support will
+be augmented on-demand depending on what makes sense for our users.
+
+## How?
+
+A preliminary quick and dirty prototype can be found
+[here](https://github.com/damienmg/bazel/commit/3a483ab53e547ae677599215faa9e3398bbd06ba)
+and
+[here](https://github.com/damienmg/bazel/commit/c40bd9c71965f0a8c85b732a0b0c3dbe31e017cf).
+
+Here what the prototype does:
+
+ 1. [First commit](https://github.com/damienmg/bazel/commit/3a483ab53e547ae677599215faa9e3398bbd06ba)
+ activate Skylark macros and repositories
+ a. Allow Skylark load statements in the WORKSPACE file by adding
+ the various hook and a WorkspaceContext.
+ b. A new repository_rule in Skylark that can be called only from
+ the WORKSPACE file.
+ c. A new repository context that is passed to repository rule and
+ that should contain all the non-hermetic stuff so the rest of
+ skylark stays hermetic.
+ d. A bit of hack for tweaking the SkylarkNativeModule when in
+ WORKSPACE file to comply with the structure of the WORKSPACE
+ rules.
+ e. A dirty hack to load the SkylarkRepositoryFunction as a Skylark
+ module without breaking the package boundaries. This is due of
+ technical debts on loading Skylark module nicely (there is a TODO
+ to do it correctly).
+ 2. [Second commit](https://github.com/damienmg/bazel/commit/c40bd9c71965f0a8c85b732a0b0c3dbe31e017cf)
+ showcase the usage of Skylark remote repositories as a configuration step.
+ a. Add an example for fetching JDK dependencies. It does both the
+ detection and the fetching.
+ b. Add the necessary methods in the SkylarkRepositoryContext for
+ making the example work.
+ c. Added the search method to the Skylark string object (to do a
+ regex search).
+
+## Roadmap
+
+The obvious choice for the roadmap is to remake all those works,
+correctly commented and tested, and then add methods to the
+SkylarkRepositoryContext for full support.
+More precisely the correct order of the work should be:
+
+1. Activate Skylark Macros taking part of 1.a and doing correctly 1.d
+ [[DONE](https://github.com/bazelbuild/bazel/commit/8ca065c2ae941309b53f95313a68e585ecc70560)]
+2. Fix Skylark module load (1.e)
+ [[DONE](https://github.com/bazelbuild/bazel/commit/f81c675928c6beeaae5f66480dc7dbef47f75fb8)]
+3. Add the SkylarkRepositoryFunction and empty context (1.b and 1.c)
+ [[DONE](https://github.com/bazelbuild/bazel/commit/653df8813dd74042e8e084eeae238a8b9f16a3ca)]
+4. [Extends SkylarkRepositoryContext for handling C++ configuration](/designs/2016/02/16/cpp-autoconf.html)
+ [[DONE](https://github.com/bazelbuild/bazel/commit/8fa5ae6a6364100f2a7f9130e62eb0edb447339a)]
+5. Extends SkylarkRepositoryContext
+ [[DONE](https://github.com/bazelbuild/bazel/commit/97f2c842ae706eccd822d8d264aba66c6102bade)]
+ for handling PyPI
+6. Document
+ [[DONE](/docs/skylark/repository_rules.html)]
+7. Extends SkylarkRepositoryContext for handling Docker pull
diff --git a/site/designs/_posts/2016-02-16-cpp-autoconf.md b/site/designs/_posts/2016-02-16-cpp-autoconf.md
new file mode 100644
index 0000000..c80fc8c
--- /dev/null
+++ b/site/designs/_posts/2016-02-16-cpp-autoconf.md
@@ -0,0 +1,145 @@
+---
+layout: contribute
+title: Generating C++ crosstool with a Skylark Remote Repository
+---
+
+# Generating C++ crosstool with a Skylark Remote Repository
+
+__Status:__ implemented
+
+__Author:__ dmarting@google.com
+
+__Reviewers:__ lberki@google.com
+
+## Context
+
+[Skylark](/docs/skylark/index.html) is the
+extension language for Bazel and lets Bazel users describe the
+build for new languages easily. External users do not create
+native rules and we want to avoid them doing so.
+
+[Remote repositories](/docs/external.html)
+are a convenient way to specify your third party dependencies
+and to fetch them along with the build if you don’t want to
+check them in your repository.
+
+[Skylark remote
+repositories](/designs/2015/07/02/skylark-remote-repositories.html) is
+an ongoing effort to support specifying new remote repositories using
+Skylark.
+
+## Why?
+
+Configurability issues are stopping users from compiling and using
+Bazel on complex setup. In particular,
+[TensorFlow](https://tensorflow.io)’s users runs on
+various hardware where gcc is installed on non-standard directory that
+needs to change the
+[CROSSTOOL](https://github.com/bazelbuild/bazel/blob/6b6ff76945c80fb8b11b71d402b5146c85b86859/tools/cpp/CROSSTOOL)
+file (see
+[issue #531](https://github.com/bazelbuild/bazel/issues/531)).
+This generally requires to change the list of include directories, the
+path to gcc and sometimes also the linking option to find the correct
+libraries at runtime. Some platform even requires
+[special wrappers around gcc](https://github.com/bazelbuild/bazel/blob/6b6ff76945c80fb8b11b71d402b5146c85b86859/tools/cpp/osx_gcc_wrapper.sh).
+
+Java solved the problem by setting a custom repository
+([@local_jdk](https://github.com/bazelbuild/bazel/blob/6b6ff76945c80fb8b11b71d402b5146c85b86859/src/main/java/com/google/devtools/build/lib/bazel/rules/java/jdk.WORKSPACE#L3))
+where the path is automatically detected using the [location of the JVM
+running
+Bazel](https://github.com/bazelbuild/bazel/blob/6b6ff76945c80fb8b11b71d402b5146c85b86859/src/main/java/com/google/devtools/build/lib/packages/WorkspaceFactory.java#L414).
+But this approach does not scale well with complex language setup like
+C++.
+
+We reduced the number of C++ issues the user had with removing all C++
+compilation in the bootstrap of Bazel. However, to properly handle
+those platform, Bazel needs some level of auto-configuration
+([Kythe](https://github.com/google/kythe/blob/a29f0adc6fa11550f66bc2278f17b89b9e02de18/setup_bazel.sh)
+and
+[Tensorflow](https://github.com/tensorflow/tensorflow/blob/a81c4f9cd01563e97fc6f179e4d70960fc9b02ae/configure)
+have their own auto-configuration scripts). This document discuss how
+to use a skylark remote repository to implement a simple
+auto-configuration for C++ crosstool (step 4 of the roadmap from the
+[Skylark remote
+repositories](/design/2015/07/02/skylark-remote-repositories.html)
+document).
+
+## C++ toolchain detection
+
+Until now here the various issues user have faced using a custom C++
+toolchain:
+
+ 1. C++ compiler is not at the expected location.
+ 2. C++ compiler is `clang` and not `gcc` or behaves differently than
+ what Bazel C++ rules expect.
+ 3. Libraries are not in the default location.
+ 4. Headers are not in the default location.
+ 5. Path of libraries or headers are outside of the default mounted
+ paths.
+
+The current fix we propose to the user for the various issue are:
+
+ 1. Change the tool paths in
+ [tools/cpp/CROSSTOOL#L87](https://github.com/bazelbuild/bazel/blob/6b6ff76945c80fb8b11b71d402b5146c85b86859/tools/cpp/CROSSTOOL#L87).
+ 2. Add a wrapper like
+ [tools/cpp/osx\_gcc\_wrapper.sh](https://github.com/bazelbuild/bazel/blob/6b6ff76945c80fb8b11b71d402b5146c85b86859/tools/cpp/osx_gcc_wrapper.sh)
+ and modify some options from the CROSSTOOL file.
+ 3. Add `-Wl,rpath,` option to the
+ [linker\_flags](https://github.com/bazelbuild/bazel/blob/6b6ff76945c80fb8b11b71d402b5146c85b86859/tools/cpp/CROSSTOOL#L93).
+ 4. Add the directories to the
+ [cxx\_builtin\_include\_dirs](https://github.com/bazelbuild/bazel/blob/6b6ff76945c80fb8b11b71d402b5146c85b86859/tools/cpp/CROSSTOOL#L100).
+ 5. Deactivate sandboxing
+
+To address those issues, we propose to add the followings methods to
+the repository context object:
+
+ 1. `which(cmd)` returns the path to the binary designed by `cmd`,
+ looking for it in the path environment variable (or equivalent).
+ This will help getting the path to the C++ compiler.
+ 2. `execute([arg0, arg1, ..., argn])` executes a command and returns an
+ `exec_result` struct containing:
+ * `stdout` the content of the standard output,
+ * `stderr` the content of the standard error output, and
+ * `return_code` the return code of the execution.
+ Executing `$(CC)` will help detect whether we are using gcc or
+ clang.
+ 3. An `os` object with an environ map containing the list of
+ environment variable. The os object will be extended to
+ contains all OS specific variables (platform name and much more).
+ 4. `execute([..])` from 2 will be used to run [`gcc ...
+-v`](http://stackoverflow.com/questions/11946294/dump-include-paths-from-g)
+ to list the built-in include directories.
+To address the issue 5, we can add the list of paths to dependencies to the
+[crosstool rule in the BUILD
+file](https://github.com/bazelbuild/bazel/wiki/Building-with-a-custom-toolchain).
+
+## Writing the cpp package
+
+Once we have resolved all the information from the system, we need to
+write two or three files:
+
+ - The `BUILD` file that will contains the corresponding
+ `cc_toolchain` rules
+ - The `CROSSTOOL` file
+ - Optionally, the wrapper script.
+
+We should extends the context with a `file(path, content)` method, where
+path is a path relative to the repository root and content the content
+of the file to write.
+
+To ease the writing of crosstool, we should also provide a
+`template(path, label, variables)` method which will write the file
+pointed by path using the file pointed by label (should be a
+FileValue) in which variables have been replaced in the same way that
+[template_action](http://bazel.io/docs/skylark/lib/ctx.html#template_action)
+works.
+
+## Rollout plan
+
+The implementation plan would be:
+
+ 1. Implements `which`, `execute`, `os`, `file` and `template`
+ [__DONE__]
+ 2. Write the `cc_configure` repository rule which does the work. Use
+ GitHub bugs as inputs on which platform to support. [__DONE__]
+ 3. Advertise the existence of `cc_configure` [__DONE__]
