<commit_before>---
layout: documentation
title: Build Tutorial - C++
---

Introduction to Bazel: Build a C++ Project
==========

In this tutorial, you'll learn the basics of building C++ applications with
Bazel. You will set up your workspace and build a simple C++ project that
illustrates key Bazel concepts, such as targets and `BUILD` files. After
completing this tutorial, take a look at
[Common C++ Build Use Cases](cpp-use-cases.md) for information on more advanced
concepts such as writing and running C++ tests.

Estimated completion time: 30 minutes.

## What you'll learn

In this tutorial you'll learn how to:

*  Build a target
*  Visualize the project's dependencies
*  Split the project into multiple targets and packages
*  Control target visibility across packages
*  Reference targets through labels

## Contents

*  [Before you begin](#before-you-begin)
   *  [Install Bazel](#install-bazel)
   *  [Get the sample project](#get-the-sample-project)
*  [Build with Bazel](#build-with-bazel)
   *  [Set up the workspace](#set-up-the-workspace)
   *  [Understand the BUILD file](#understand-the-build-file)
   *  [Build the project](#build-the-project)
   *  [Review the dependency graph](#review-the-dependency-graph)
*  [Refine your Bazel build](#refine-your-bazel-build)
   *  [Specify multiple build targets](#specify-multiple-build-targets)
   *  [Use multiple packages](#use-multiple-packages)
*  [Use labels to reference targets](#use-labels-to-reference-targets)
*  [Further reading](#further-reading)

## Before you begin

To prepare for the tutorial, first [Install Bazel](../install.md) if
you don't have it installed already. Then, retrieve the sample project from
Bazel's GitHub repository:

```
git clone https://github.com/bazelbuild/examples/
```

The sample project for this tutorial is in the `examples/cpp-tutorial` directory
and is structured as follows:


```
examples
└── cpp-tutorial
    ├──stage1
    │  └── main
    │      ├── BUILD
    │      ├── hello-world.cc
    │  └── WORKSPACE
    ├──stage2
    │  ├── main
    │  │   ├── BUILD
    │  │   ├── hello-world.cc
    │  │   ├── hello-greet.cc
    │  │   ├── hello-greet.h
    │  └── WORKSPACE
    └──stage3
       ├── main
       │   ├── BUILD
       │   ├── hello-world.cc
       │   ├── hello-greet.cc
       │   └── hello-greet.h
       ├── lib
       │   ├── BUILD
       │   ├── hello-time.cc
       │   └── hello-time.h
       └── WORKSPACE
```

As you can see, there are three sets of files, each set representing a stage in
this tutorial. In the first stage, you will build a single target residing in a
single package. In the second stage, you will split your project into multiple
targets but keep it in a single package. In the third and final stage, you will
split your project into multiple packages and build it with multiple targets.

## Build with Bazel

### Set up the workspace

Before you can build a project, you need to set up its workspace. A workspace is
a directory that holds your project's source files and Bazel's build outputs. It
also contains files that Bazel recognizes as special:

*  The `WORKSPACE` file, which identifies the directory and its contents as a
   Bazel workspace and lives at the root of the project's directory structure,

*  One or more `BUILD` files, which tell Bazel how to build different parts of
   the project. (A directory within the workspace that contains a `BUILD` file
   is a *package*. You will learn about packages later in this tutorial.)

To designate a directory as a Bazel workspace, create an empty file named
`WORKSPACE` in that directory.

When Bazel builds the project, all inputs and dependencies must be in the same
workspace. Files residing in different workspaces are independent of one
another unless linked, which is beyond the scope of this tutorial.

### Understand the BUILD file

A `BUILD` file contains several different types of instructions for Bazel.
The most important type is the *build rule*, which tells Bazel how to build the
desired outputs, such as executable binaries or libraries. Each instance
of a build rule in the `BUILD` file is called a *target* and points to a
specific set of source files and dependencies. A target can also point to other
targets.

Take a look at the `BUILD` file in the `cpp-tutorial/stage1/main` directory:

```
cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
)
```

In our example, the `hello-world` target instantiates Bazel's built-in
[`cc_binary` rule](../be/c-cpp.html#cc_binary). The rule tells Bazel to build
a self-contained executable binary from the `hello-world.cc` source file with no
dependencies.

The attributes in the target explicitly state its dependencies and options.
While the `name` attribute is mandatory, many are optional. For example, in the
`hello-greet` target, `name` is self-explanatory, and `srcs` specifies the
source file(s) from which Bazel builds the target.

### Build the project

Let's build your sample project. Change into the `cpp-tutorial/stage1` directory
and run the following command:

```
bazel build //main:hello-world
```
<commit_msg>Fix target label.<commit_after>---
layout: documentation
title: Build Tutorial - C++
---

Introduction to Bazel: Build a C++ Project
==========

In this tutorial, you'll learn the basics of building C++ applications with
Bazel. You will set up your workspace and build a simple C++ project that
illustrates key Bazel concepts, such as targets and `BUILD` files. After
completing this tutorial, take a look at
[Common C++ Build Use Cases](cpp-use-cases.md) for information on more advanced
concepts such as writing and running C++ tests.

Estimated completion time: 30 minutes.

## What you'll learn

In this tutorial you'll learn how to:

*  Build a target
*  Visualize the project's dependencies
*  Split the project into multiple targets and packages
*  Control target visibility across packages
*  Reference targets through labels

## Contents

*  [Before you begin](#before-you-begin)
   *  [Install Bazel](#install-bazel)
   *  [Get the sample project](#get-the-sample-project)
*  [Build with Bazel](#build-with-bazel)
   *  [Set up the workspace](#set-up-the-workspace)
   *  [Understand the BUILD file](#understand-the-build-file)
   *  [Build the project](#build-the-project)
   *  [Review the dependency graph](#review-the-dependency-graph)
*  [Refine your Bazel build](#refine-your-bazel-build)
   *  [Specify multiple build targets](#specify-multiple-build-targets)
   *  [Use multiple packages](#use-multiple-packages)
*  [Use labels to reference targets](#use-labels-to-reference-targets)
*  [Further reading](#further-reading)

## Before you begin

To prepare for the tutorial, first [Install Bazel](../install.md) if
you don't have it installed already. Then, retrieve the sample project from
Bazel's GitHub repository:

```
git clone https://github.com/bazelbuild/examples/
```

The sample project for this tutorial is in the `examples/cpp-tutorial` directory
and is structured as follows:


```
examples
└── cpp-tutorial
    ├──stage1
    │  └── main
    │      ├── BUILD
    │      ├── hello-world.cc
    │  └── WORKSPACE
    ├──stage2
    │  ├── main
    │  │   ├── BUILD
    │  │   ├── hello-world.cc
    │  │   ├── hello-greet.cc
    │  │   ├── hello-greet.h
    │  └── WORKSPACE
    └──stage3
       ├── main
       │   ├── BUILD
       │   ├── hello-world.cc
       │   ├── hello-greet.cc
       │   └── hello-greet.h
       ├── lib
       │   ├── BUILD
       │   ├── hello-time.cc
       │   └── hello-time.h
       └── WORKSPACE
```

As you can see, there are three sets of files, each set representing a stage in
this tutorial. In the first stage, you will build a single target residing in a
single package. In the second stage, you will split your project into multiple
targets but keep it in a single package. In the third and final stage, you will
split your project into multiple packages and build it with multiple targets.

## Build with Bazel

### Set up the workspace

Before you can build a project, you need to set up its workspace. A workspace is
a directory that holds your project's source files and Bazel's build outputs. It
also contains files that Bazel recognizes as special:

*  The `WORKSPACE` file, which identifies the directory and its contents as a
   Bazel workspace and lives at the root of the project's directory structure,

*  One or more `BUILD` files, which tell Bazel how to build different parts of
   the project. (A directory within the workspace that contains a `BUILD` file
   is a *package*. You will learn about packages later in this tutorial.)

To designate a directory as a Bazel workspace, create an empty file named
`WORKSPACE` in that directory.

When Bazel builds the project, all inputs and dependencies must be in the same
workspace. Files residing in different workspaces are independent of one
another unless linked, which is beyond the scope of this tutorial.

### Understand the BUILD file

A `BUILD` file contains several different types of instructions for Bazel.
The most important type is the *build rule*, which tells Bazel how to build the
desired outputs, such as executable binaries or libraries. Each instance
of a build rule in the `BUILD` file is called a *target* and points to a
specific set of source files and dependencies. A target can also point to other
targets.

Take a look at the `BUILD` file in the `cpp-tutorial/stage1/main` directory:

```
cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
)
```

In our example, the `hello-world` target instantiates Bazel's built-in
[`cc_binary` rule](../be/c-cpp.html#cc_binary). The rule tells Bazel to build
a self-contained executable binary from the `hello-world.cc` source file with no
dependencies.

The attributes in the target explicitly state its dependencies and options.
While the `name` attribute is mandatory, many are optional. For example, in the
`hello-world` target, `name` is self-explanatory, and `srcs` specifies the
source file(s) from which Bazel builds the target.

### Build the project

Let's build your sample project. Change into the `cpp-tutorial/stage1` directory
and run the following command:

```
bazel build //main:hello-world
```

{'fraction_non_alphanumeric': 0.09503809337761282, 'fraction_numerical': 0.0013674545809728462, 'mean_word_length': 3.6414324569356302, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6927840', 'n_tokens_mistral': 3114, 'n_tokens_neox': 2995, 'n_words': 1366}