diff options
author | David Chen <dzc@google.com> | 2016-08-24 10:55:41 +0000 |
---|---|---|
committer | John Cater <jcater@google.com> | 2016-08-24 20:00:23 +0000 |
commit | 8fe82a386e215150835fdd657dc03e23277f9b1c (patch) | |
tree | f08e75e4fe8c448eaa04cb5dfaa24bd2e8914259 /site/versions/master/docs/getting-started.md | |
parent | 833fa078e2ae5150e226f9251cec2ffee9e3a887 (diff) |
Branch Bazel docs into version directory.
--
MOS_MIGRATED_REVID=131156143
Diffstat (limited to 'site/versions/master/docs/getting-started.md')
-rw-r--r-- | site/versions/master/docs/getting-started.md | 97 |
1 files changed, 97 insertions, 0 deletions
diff --git a/site/versions/master/docs/getting-started.md b/site/versions/master/docs/getting-started.md new file mode 100644 index 0000000000..0e91dd3b13 --- /dev/null +++ b/site/versions/master/docs/getting-started.md @@ -0,0 +1,97 @@ +--- +layout: documentation +title: Getting Started +--- + +# Getting Started with Bazel + +## Setup + +Use the [installation instructions](/docs/install.html) to install a copy of +Bazel on your machine. + +## Using a Workspace + +All Bazel builds take place in a [_workspace_](/docs/build-ref.html#workspaces), +a directory on your filesystem that contains source code for the software you +want to build, as well symbolic links to directories that contain the build +outputs (for example, `bazel-bin` and `bazel-out`). The location of the +workspace directory is not significant, but it must contain a file called +`WORKSPACE` in the top-level directory; an empty file is a valid workspace. +The `WORKSPACE` file can be used to reference +[external dependencies](/docs/external.html) required to build the outputs. +One workspace can be shared among multiple projects if desired. + +```bash +$ touch WORKSPACE +``` + +## Creating a Build File + +To know which targets can be built in your project, Bazel inspects `BUILD` +files. They are written in Bazel's build language which is syntactically +similar to Python. Usually they are just a sequence of declarations of rules. +Each rule specifies its inputs, outputs, and a way to compute the outputs from +the inputs. + +The rule probably most familiar to people who have used `Makefile`s before (as +it is the only rule available there) is the +[genrule](/docs/be/general.html#genrule), which specifies how the output can +be generated by invoking a shell command. + +``` +genrule( + name = "hello", + outs = ["hello_world.txt"], + cmd = "echo Hello World > $@", +) +``` + +The shell command may contain [Make variables](/docs/be/make-variables.html). + +Using the above `BUILD` file, you can ask Bazel to generate the target. + +``` +$ bazel build :hello +. +INFO: Found 1 target... +Target //:hello up-to-date: + bazel-genfiles/hello_world.txt +INFO: Elapsed time: 2.255s, Critical Path: 0.07s +``` + +We note two things. First, targets are normally referred to by their +[label](/docs/build- ref.html#labels), which is specified by the +[name](/docs/be/general.html#genrule.name) attribute of the rule. (Referencing +them by the output file name is also possible, but this is not the preferred +way.) Second, Bazel puts the generated files into a separate directory (the +`bazel-genfiles` directory is actually a symbolic link) so as not to pollute +your source tree. + +Rules may use the output of other rules as input, as in the following +example. Again, the generated sources are referred to by their label. + +``` +genrule( + name = "hello", + outs = ["hello_world.txt"], + cmd = "echo Hello World > $@", +) + +genrule( + name = "double", + srcs = [":hello"], + outs = ["double_hello.txt"], + cmd = "cat $< $< > $@", +) +``` + +Finally, note that, while the [genrule](/docs/be/general.html#genrule) might +seem familiar, it usually is _not_ the best rule to use. It is preferrable to +use one of the specialized [rules](/docs/be/overview.html#rules) for various +languages. + +# Next Steps + +Next, check out the tutorial on building [java](/docs/tutorial/java.html) +or [C++](/docs/tutorial/cpp.html) programs. |