diff options
author | David Chen <dzc@google.com> | 2015-07-23 15:04:50 +0000 |
---|---|---|
committer | Damien Martin-Guillerez <dmarting@google.com> | 2015-07-27 08:31:47 +0000 |
commit | 3f16b561a68fdb1eaa865501420c9b87b44809ae (patch) | |
tree | 93ad617fbc729c6f15185bccfc414461301e3c22 /site | |
parent | 9d659ad0a1024544eb6275391b56660a1d981109 (diff) |
Minor documentation fixes. Make sidebar navigation look more consistent.
--
MOS_MIGRATED_REVID=98934930
Diffstat (limited to 'site')
-rw-r--r-- | site/contributing.md | 13 | ||||
-rw-r--r-- | site/docs/cpp.md | 6 | ||||
-rw-r--r-- | site/docs/external.md | 59 | ||||
-rw-r--r-- | site/docs/skylark/rules.md | 3 | ||||
-rw-r--r-- | site/governance.md | 7 |
5 files changed, 47 insertions, 41 deletions
diff --git a/site/contributing.md b/site/contributing.md index d5966a0101..e02b8e873c 100644 --- a/site/contributing.md +++ b/site/contributing.md @@ -4,8 +4,8 @@ layout: community # Contributing to Bazel -We welcome contributions! This page covers setting up your machine to develop -Bazel and, when you've made a patch, how to submit it. +<p class="lead">We welcome contributions! This page covers setting up your +machine to develop Bazel and, when you've made a patch, how to submit it.</p> ## How can I contribute to Bazel? @@ -23,9 +23,7 @@ a lot of time in a patch. <li>Prepare a git commit that implements the feature. Don't forget to add tests. <li>Create a new code review on <a href="https://bazel-review.googlesource.com">Gerrit</a> by running: - <pre> -$ git push https://bazel.googlesource.com/bazel HEAD:refs/for/master - </pre> + <pre>$ git push https://bazel.googlesource.com/bazel HEAD:refs/for/master</pre> Gerrit upload requires that you: <ul> <li>Have signed a @@ -76,7 +74,8 @@ To work with IntelliJ, run `sh scripts/setup-intellij.sh` from the root of the source tree and it will create the necessary project files. You can then open the folder as a project in IntelliJ. -### Compiling Bazel {#compile-bazel} +<a name="compile-bazel"></a> +### Compiling Bazel To test out bazel, you need to compile it. There is currently two ways of compiling it: @@ -103,10 +102,12 @@ When modifying Bazel, you want to make sure that the following still works: Start creating a debug configuration for both C++ and Java in your bazelrc with the following: +``` build:debug -c dbg build:debug --javacopt="-g" build:debug --copt="-g" build:debug --strip="never" +``` Then you can rebuild Bazel with `bazel build --config debug //src:bazel` and use your favorite debugger to start debugging. diff --git a/site/docs/cpp.md b/site/docs/cpp.md index 4ce0374e11..8f8900dcda 100644 --- a/site/docs/cpp.md +++ b/site/docs/cpp.md @@ -112,8 +112,8 @@ cc_library( ) ``` -This expresses that the "sandwich" library depends on the "bread" library, -which depends on the "flour" library. +This expresses that the `sandwich` library depends on the `bread` library, +which depends on the `flour` library. Adding include paths -------------------- @@ -177,7 +177,7 @@ more complicated: link errors for duplicate symbols. * It uses header files that relative to the `gtest-1.7.0/include/` directory (`"gtest/gtest.h"`), so we must add that directory the includes. -* It uses "private" header files in src/, so we add "." to the includes so it +* It uses "private" header files in `src/`, so we add `.` to the includes so it can `#include "src/gtest-internal-inl.h"`. * It needs to link in pthread, so we add that as a `linkopt`. diff --git a/site/docs/external.md b/site/docs/external.md index 583aaabe87..e11f49fdd9 100644 --- a/site/docs/external.md +++ b/site/docs/external.md @@ -10,8 +10,8 @@ impractical for some version control systems and goes against how many existing projects are structured. Thus, Bazel has a system for pulling in dependencies from outside of the build root. -External dependencies can be specified in a _WORKSPACE_ file in the build root. -This _WORKSPACE_ file uses the same Python-like syntax of BUILD files, but +External dependencies can be specified in a `WORKSPACE` file in the build root. +This `WORKSPACE` file uses the same Python-like syntax of BUILD files, but allows a different set of rules. See the full list of rules that are allowed in the [Workspace](/docs/build-encyclopedia.html) list of rules in the Build Encyclopedia. @@ -22,24 +22,25 @@ By default, external dependencies are fetched as needed during `bazel build`. If you would like to disable this behavior or prefetch dependencies, use [`bazel fetch`](http://bazel.io/docs/bazel-user-manual.html#fetch). +<a name="transitive-dependencies"></a> ## Transitive dependencies -Bazel only reads dependencies listed in your build root's _WORKSPACE_ file. This -means that if your project (_A_) depends on another project (_B_) which list a -dependency on project _C_ in its _WORKSPACE_ file, you'll have to add both _B_ -and _C_ to your project's _WORKSPACE_ file. This can balloon the _WORKSPACE_ -file size, but hopefully limits the chances of having one library include _C_ -at version 1.0 and another include _C_ at 2.0. +Bazel only reads dependencies listed in your build root's `WORKSPACE` file. This +means that if your project (`A`) depends on another project (`B`) which list a +dependency on project `C` in its `WORKSPACE` file, you'll have to add both `B` +and `C` to your project's `WORKSPACE` file. This can balloon the `WORKSPACE` +file size, but hopefully limits the chances of having one library include `C` +at version 1.0 and another include `C` at 2.0. -Bazel provides a tool to help generate these expansive _WORKSPACE_ files, called +Bazel provides a tool to help generate these expansive `WORKSPACE` files, called `generate_workspace`. Run the following to build the tool and see usage: ``` bazel run src/main/java/com/google/devtools/build/workspace:generate_workspace ``` -You can either specify directories containing Bazel projects (i.e., _WORKSPACE_ -files) or Maven projects (i.e., _pom.xml_ files). For example: +You can either specify directories containing Bazel projects (i.e., `WORKSPACE` +files) or Maven projects (i.e., `pom.xml` files). For example: ```bash $ bazel run src/main/java/com/google/devtools/build/workspace:generate_workspace -- \ @@ -51,17 +52,17 @@ Wrote: /tmp/1437415510621-0/2015-07-20-14-05-10.BUILD ``` -The _WORKSPACE_ file contains the transitive dependencies of given projects. The -_BUILD_ file contains a single target, `transitive-deps`, that contains all of +The `WORKSPACE` file contains the transitive dependencies of given projects. The +`BUILD` file contains a single target, `transitive-deps`, that contains all of the dependencies. You can copy these files to your project and add -`transitive-deps` as a dependency of your `java_` targets in _BUILD_ files. +`transitive-deps` as a dependency of your `java_` targets in `BUILD` files. If you specify multiple Bazel or Maven projects, they will all be combined into -one _WORKSPACE_ file (e.g., if the Bazel project depends on junit and the Maven +one `WORKSPACE` file (e.g., if the Bazel project depends on junit and the Maven project also depends on junit, junit will only appear once as a dependency in the output). -You may wish to curate the generated _WORKSPACE_ file to ensure it is using the +You may wish to curate the generated `WORKSPACE` file to ensure it is using the correct version of each dependency. If several different versions of an artifact are requested (by different libraries that depend on it), then `generate_workspace` chooses a version and annotates the `maven_jar` with the @@ -82,7 +83,7 @@ maven_jar( This indicates that `org.springframework:spring:2.5.6`, `javax.mail:mail:1.4`, `httpunit:httpunit:1.6`, `org.springframework:spring-support:2.0.2`, and `org.slf4j:nlog4j:1.2.24` all depend on javax.activation. However, two of these -libraries wanted version 1.1 and three of them wanted 1.0.2. The _WORkSPACE_ +libraries wanted version 1.1 and three of them wanted 1.0.2. The `WORkSPACE` file is using version 1.1, but that might not be the right version to use. You may also want to break `transitive-deps` into smaller targets, as it is @@ -101,11 +102,11 @@ use or [`http_archive`](http://bazel.io/docs/build-encyclopedia.html#http_archive) to symlink it from the local filesystem or download it (respectively). -For example, suppose you are working on a project, _my-project/_, and you want -to depend on targets from your coworker's project, _coworkers-project/_. Both +For example, suppose you are working on a project, `my-project/`, and you want +to depend on targets from your coworker's project, `coworkers-project/`. Both projects use Bazel, so you can add your coworker's project as an external dependency and then use any targets your coworker has defined from your own -BUILD files. You would add the following to _my\_project/WORKSPACE_: +BUILD files. You would add the following to `my\_project/WORKSPACE`: ```python local_repository( @@ -124,10 +125,10 @@ Rules prefixed with `new_` (e.g., and [`new_http_archive`](http://bazel.io/docs/build-encyclopedia.html#new_http_archive) allow you to create targets from projects that do not use Bazel. -For example, suppose you are working on a project, _my-project/_, and you want -to depend on your coworker's project, _coworkers-project/_. Your coworker's +For example, suppose you are working on a project, `my-project/`, and you want +to depend on your coworker's project, `coworkers-project/`. Your coworker's project uses `make` to build, but you'd like to depend on one of the .so files -it generates. To do so, add the following to _my\_project/WORKSPACE_: +it generates. To do so, add the following to `my_project/WORKSPACE`: ```python new_local_repository( @@ -154,18 +155,18 @@ files. # Caching of external dependencies Bazel caches external dependencies and only re-downloads or updates them when -the _WORKSPACE_ file changes. If the _WORKSPACE_ file does not change, Bazel +the `WORKSPACE` file changes. If the `WORKSPACE` file does not change, Bazel assumes that the external dependencies have not changed, either. This can cause unexpected results, especially with local repositories. -For instance, in the example above, suppose that _my-project/_ has a target that +For instance, in the example above, suppose that `my-project/` has a target that depends on `@coworkers-project//:a`, which you build. Then you change to -_coworkers-project/_ and pull the latest updates to their library, which changes -the behavior of `@coworkers-project//:a`. If you go back to _my-project/_ and +`coworkers-project/` and pull the latest updates to their library, which changes +the behavior of `@coworkers-project//:a`. If you go back to `my-project/` and build your target again, it will assume `@coworkers-project//:a` is already up-to-date and reuse the cached library (instead of realizing that the sources have changed and, thus, rebuilding). To avoid this situation, prefer remote repositories to local ones and do not -manually change the files in _\[output\_base\]/external_. If you change a file -in _\[output\_base\]/external_, rerun `bazel fetch ...` to update the cache. +manually change the files in `[output_base]/external`. If you change a file +in `[output_base]/external`, rerun `bazel fetch ...` to update the cache. diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md index b3204fa4af..8338e6e69e 100644 --- a/site/docs/skylark/rules.md +++ b/site/docs/skylark/rules.md @@ -111,7 +111,8 @@ my_rule = rule( ) ``` -Output files {#output-files} +<a name="output-files"></a> +Output files ------------ A target can declare output files, which must be generated by the target's diff --git a/site/governance.md b/site/governance.md index 548952ad7a..c94b110ff7 100644 --- a/site/governance.md +++ b/site/governance.md @@ -53,7 +53,7 @@ list), but this will hopefully change over time. extension points if they do not run counter to the internal requirements of any of the core contributors. -## Are you done open sourcing Bazel? {#isbazelopen} +## Are you done open sourcing Bazel? Open sourcing Bazel is a work-in-progress. In particular, we're still working on open sourcing: @@ -75,7 +75,10 @@ not available on GitHub and probably never will be. ### Core Contributors -__Contact the core team at bazel-discuss@googlegroups.com.__ +<p class="lead"> +Contact the core team at <a href="mailto:bazel-dev@googlegroups.com"> +bazel-dev@googlegroups.com</a>. +</p> The current group is: |