diff --git a/README.md b/README.md index 7cda78aacf077e..929de70c3f5ead 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ *{Fast, Correct} - Choose two* -Bazel is an build tool that builds code quickly and reliably. +Bazel is a build tool that builds code quickly and reliably. It executes as few build steps as possible by tracking dependencies and outputs, controls the build environment to keep builds hermetic, and uses its knowledge of dependencies to parallelize builds. @@ -13,9 +13,9 @@ knowledge of dependencies to parallelize builds. * How to [install Bazel](docs/install.md) * How to [get started using Bazel](docs/getting-started.md) - * How to [use the query command](docs/bazel-query-v2.html) - * How to [extend Bazel](docs/skylark/index.md) * The rule reference documentation is in the [build encyclopedia](docs/build-encyclopedia.html). + * How to [use the query command](docs/bazel-query.html) + * How to [extend Bazel](docs/skylark/index.md) * TODO(bazel-team): link to the user-manual * TODO(bazel-team): link to the test encyclopedia? diff --git a/docs/FAQ.md b/docs/FAQ.md index fca9aa6024706a..3b62ff8a135c65 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -13,8 +13,9 @@ What is special about Bazel? Bazel was designed to fit the way software is developed at Google. It has the following features: -* Multi-language support: Bazel supports Java and C++ out of the box, - and can be extended to support arbitrary programming languages. +* Multi-language support: Bazel supports Java, Objective-C and C++ out + of the box, and can be extended to support arbitrary programming + languages. * High-level build language: Projects are described in the BUILD language, a concise text format that describes a project as sets of @@ -106,7 +107,7 @@ that this is fast enough for most of our users. How does the Google development process work? ---------------------------------------------- -For our server code, we use the following development workflow: +For our server code base, we use the following development workflow: * All of our server code base is in a single, gigantic version control system. @@ -119,7 +120,7 @@ For our server code, we use the following development workflow: * Branching is primarily used for managing releases, so everybody develops their software at head. -Bazel is a cornerstones of this philosophy: since Bazel requires all +Bazel is a cornerstone of this philosophy: since Bazel requires all dependencies to be fully specified, we can predict which programs and tests are affected by a change, and vet them before submission. @@ -185,11 +186,11 @@ straightforward, provided a JDK is available for the platform. What about Windows? ------------------- -We have experimented with a Windows port using MinGW/MSYS (see -README.windows), but have no plans to invest in this port right -now. Due to its Unix heritage, porting Bazel is significant work. For -example, Bazel uses symlinks extensively, which has varying levels of -support across Windows versions. +We have experimented with a Windows port +[using MinGW/MSYS](windows.md), but have no plans to invest in this +port right now. Due to its Unix heritage, porting Bazel is significant +work. For example, Bazel uses symlinks extensively, which has varying +levels of support across Windows versions. What should I not use Bazel for? @@ -220,19 +221,8 @@ versions multiple times every month. In short, except for features marked as experimental, at any point in time, Bazel should Just Work. Changes to non-experimental rules will -be backward compatible. - -You can recognize the different experimental features as follows: - -* Options: Experimental features start with --experimental_. - -* Rules: Experimental rules are undocumented in the - build encyclopedia. TODO(bazel-team): add link. - -* Attributes: Experimental rule attributes are undocumented in the - build encyclopedia. TODO(bazel-team): add link. - -* TODO(bazel-team): document skylark status more precisely. +be backward compatible. A more detailed list of feature support +statuses can be found in our [support document](support.md). How stable is Bazel as a binary? @@ -247,7 +237,7 @@ How can I start using Bazel? See our [getting started doc](getting-started.md) -TODO(bazel-team): more doc links +TODO(bazel-team): link to an index of all our docs. Why do I need to have a tools/ directory in my source tree? @@ -265,11 +255,11 @@ do this in a directory called "tools". Bazel allows tools such as the JDK to live outside your workspace, but the configuration data for this (where is the JDK, where is the C++ compiler?) still needs to be somewhere, and that place is also the -tools/ directory. +`tools/` directory. -Bazel comes with a base_workspace/ directory, containing a minimal set +Bazel comes with a `base_workspace/` directory, containing a minimal set of configuration files, suitable for running toolchains from standard -system directories, e.g., /usr/bin/. +system directories, e.g., `/usr/bin/`. Doesn't Docker solve the reproducibility problems? @@ -284,9 +274,10 @@ It does not address reproducibility with regard to changes in the source code. Running Make with an imperfectly written Makefile inside a Docker container can still yield unpredictable results. -Inside Google, we check in tools for reproducibility. In this way, we -can vet changes to tools ("upgrade GCC to 4.6.1") with the same -mechanism as changes to base libraries ("fix bounds check in OpenSSL"). +Inside Google, we check tools into source control for reproducibility. +In this way, we can vet changes to tools ("upgrade GCC to 4.6.1") with +the same mechanism as changes to base libraries ("fix bounds check in +OpenSSL"). Will Bazel make my builds reproducible automatically? @@ -311,7 +302,7 @@ will need to take some extra care: traversal is randomized in many programming languages. TODO(bazel-team): maybe this should be part of the skylark docs -instead. +instead, or the genrule docs? Do you have binary releases? @@ -357,9 +348,11 @@ files for python: https://github.com/google/bazel/blob/master/base_workspace/tools/build_rules/py_rules.bzl https://github.com/google/bazel/tree/master/base_workspace/examples/py -Our internal Python rules support internal use-cases which rely heavily -on native extensions, and its supporting infrastructure is specific to -us, so we have no plans to open-source it. +We are working on opening up a subset of our internal Python rules, so +they can be used as helper scripts as part of a build. + +We currently have no plans to provide packaging up of self-contained +Python binaries. @@ -407,7 +400,8 @@ We are reachable at bazel-discuss@googlegroups.com. Where do I report bugs? ----------------------- -Send us e-mail at bazel-discuss@googlegroups.com. +Send e-mail to bazel-discuss@googlegroups.com, or file a bug at +[on github](https://github.com/google/bazel/issues). diff --git a/docs/getting-started.md b/docs/getting-started.md index ba5523ed08c358..f67810f0c575b8 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -69,7 +69,7 @@ Writing Your Own Build Rules Now you can start adding your own build rules. This example assumes that _my-project/_ is a Java project. See the -[build encyclopedia](https://github.com/google/bazel/blob/master/docs/historical/build-encyclopedia.html) +[build encyclopedia](build-encyclopedia.html) for advice on writing rules for other languages. Note that when we ran "bazel build" above, the third argument started with a @@ -101,7 +101,7 @@ Python, but each build rule looks like a Python function call and you can use "hello-world"). `srcs` lists the Java source files Bazel should compile into a Java binary. `glob(["**/*.java"])` is a handy shorthand for "recursively include every file that ends with .java" (see the -[user manual](https://github.com/google/bazel/blob/master/docs/historical/bazel-user-manual.html) +[user manual](bazel-user-manual.html) for more information about globbing). Replace `com.example.ProjectRunner` with the class that contains the main method. @@ -271,7 +271,7 @@ INFO: Running command line: bazel-bin/my-project/java/com/example/cmdline/runner Hi! ``` -See the [build encyclopedia](https://github.com/google/bazel/blob/master/docs/historical/build-encyclopedia.html) for more visibility options. +See the [build encyclopedia](build-encyclopedia.html) for more visibility options. Deploying --------- @@ -307,9 +307,9 @@ Next Steps ---------- You can now create your own targets and compose them. See the [build -encyclopedia](https://github.com/google/bazel/blob/master/docs/historical/build-encyclopedia.html) +encyclopedia](build-encyclopedia.html) and Bazel -[user manual](https://github.com/google/bazel/blob/master/docs/historical/bazel-user-manual.html) +[user manual](bazel-user-manual.html) for more information. [Let us know](https://groups.google.com/forum/#!forum/bazel-discuss) if you have any questions! diff --git a/docs/install.md b/docs/install.md index e7bd9f4882831c..557fcd5e693d5f 100644 --- a/docs/install.md +++ b/docs/install.md @@ -39,9 +39,10 @@ To build Bazel on Ubuntu: Using Bazel on Mac OS X requires: -* Xcode and Xcode command line tools -* MacPorts or Homebrew for installing required packages -* A JDK 8 installed +* The Xcode command line tools. Xcode can be downloaded from + [Apbple's developer site](https://developer.apple.com/xcode/downloads/). +* MacPorts or Homebrew for installing required packages. +* An installation of JDK 8. To build Bazel on Mac OS X: @@ -59,17 +60,25 @@ To build Bazel on Mac OS X: $ cd bazel $ ./compile.sh -## Running Bazel +3. Run it + + $ ./output/bazel help -The Bazel executable is located at `<bazel_home>/output/bazel`. -You must run Bazel from within a _workspace directory_. Bazel provides a default -workspace directory with sample `BUILD` files and source code in -`<bazel_home>/base_workspace`. The default workspace contains files and -directories that must be present in order for Bazel to work. If you want to -build from source outside the default workspace directory, copy the entire -`base_workspace` directory to the new location before adding your `BUILD` and -source files. +## Running Bazel + +The Bazel executable is located at `output/bazel`, under the source +tree root. + +You must run Bazel from within source code tree, which is properly +configured for use with Bazel. We call such a tree a _workspace +directory_. Bazel provides a default workspace directory with sample +`BUILD` files and source code in `base_workspace`. The default +workspace contains files and directories that must be present in order +for Bazel to work. If you want to build from source outside the +default workspace directory, copy the entire `base_workspace` +directory to the new location before adding your `BUILD` and source +files. Build a sample Java application: diff --git a/docs/bazel-query-v2.html b/docs/query.html similarity index 100% rename from docs/bazel-query-v2.html rename to docs/query.html diff --git a/docs/roadmap.md b/docs/roadmap.md index 1ecc6d36ea8f03..dae285f0848a29 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -46,9 +46,8 @@ Alpha users will need to build Bazel from source; we will not provide binary releases until the beta. We will accept code contributions, but may need to reject or defer code contributions related to beta features still under development. Some features will be fully supported -henceforward, others are still experimental or partially supported; see -bazel/docs/governance.md for details. - +henceforward, others are still experimental or partially supported; +see our [feature support document](support.md) for details. The following features/capabilities will be available in the alpha: diff --git a/docs/support.md b/docs/support.md index e449d64ce47f48..576251a7a7a633 100644 --- a/docs/support.md +++ b/docs/support.md @@ -1,15 +1,18 @@ # Support Policy -We generally avoid making incompatible changes. At Google, we run all of the tests in the entire -depot before every release and check that there are no regressions. It is much more difficult to do -that outside of Google, because there is no single source repository that contains everything. +We generally avoid making backward-incompatible changes. At Google, we +run all of the tests in the entire depot before every release and +check that there are no regressions. It is much more difficult to do +that outside of Google, because there is no single source repository +that contains everything. All undocumented features (attributes, rules, "Make" variables, and flags) are subject to change at any time without prior notice. Features that are documented but marked *experimental* are also subject to change at any time without prior notice. The Skylark macro and rules language (anything you write in a `.bzl` file) is still subject to change. -Bugs can be reported in the [GitHub bugtracker](https://github.com/google/bazel/issues). We will +Bugs can be reported in the +[GitHub bugtracker](https://github.com/google/bazel/issues). We will make an effort to triage all reported issues within 2 business days; we will measure our triaging process and regularly report numbers. diff --git a/third_party/README.md b/third_party/README.md index 9bdd67147b98b6..753ed716796c46 100644 --- a/third_party/README.md +++ b/third_party/README.md @@ -1,3 +1,8 @@ +This file lists license and version information of all code we did not +author, but ship together with the source so building Bazel requires +a minimal set of extra dependencies. + + [aether](http://eclipse.org/aether/) --------