docs/getting_started.md

# Getting Started

To get started, first make sure you have Bazel's skylib version 1.7.1 or greater. If
you don't have it, you can use:

```
http_archive(
    name = "bazel_skylib",
    sha256 = "bc283cdfcd526a52c3201279cda4bc298652efa898b10b4db0837dc51652756f",
    urls = [
        "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/1.7.1/bazel-skylib-1.7.1.tar.gz",
        "https://github.com/bazelbuild/bazel-skylib/releases/download/1.7.1/bazel-skylib-1.7.1.tar.gz",
    ],
)

load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")

bazel_skylib_workspace()
```

## Usage in WORKSPACE

To grab the zephyr-bazel repo, use a git_repository rule in your WORKSPACE,
such as:

```
git_repository(
    name = "zephyr-bazel",
    remote = "https://pigweed.googlesource.com/zephyr/zephyr-bazel",
    branch = "main",
)
```

Once you have `@zephyr-bazel`, we can load the patch rule to generate the
Zephyr diff that will augment Zephyr to include the BUILD.zephyr rules.

```
load("@zephyr-bazel//:setup.bzl", "create_zephyr_patch_file")

create_zephyr_patch_file(
    name = "zephyr-patch",
    filename = "patch.diff",
    # This is optional, use it to see what's going on under the hood
    debug = True,
)
```

We now have a diff file at `@zephyr-patch//:patch.diff`. We're ready to load
Zephyr.

```
git_repository(
    name = "zephyr",
    remote = "https://github.com/zephyrproject-rtos/zephyr.git",
    branch = "main",
    patches = [
        "@zephyr-patch//:patch.diff",
    ],
)
```

The final step will be to load Zephyr's python dependencies:

```
load("@rules_python//python:pip.bzl", "pip_parse")

pip_parse(
    name = "py_deps",
    python_interpreter_target = interpreter,
    requirements_lock = "@@zephyr//:scripts/requirements-base.txt",
)

load("@py_deps//:requirements.bzl", zephyr_install_deps = "install_deps")

zephyr_install_deps()
```

## Usage in bzlmod

To use zephyr-bazel in bzlmod, first add it as a dependency in your project's
MODULE.bazel:

```
bazel_dep(name = "zephyr-bazel")
git_override(
    module_name = "zephyr-bazel",
    remote = "https://pigweed.googlesource.com/zephyr/zephyr-bazel",
    branch = "main",
)
```

Then use the zephyr_patch_file module extension to generate a patch file and
a Bazel repo with the patch file applied:

```
zephyr_patch_file = use_extension("@zephyr-bazel//:setup.bzl", "zephyr_patch_file")
use_repo(zephyr_patch_file, "zephyr")
```

`pip` is required by the patched zephyr repo, so your project needs to inject
it:

```
pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip")
# Load the Zephyr pip requirements
pip.parse(
    hub_name = "pip",
    python_version = "3.11",
    requirements_lock = "@zephyr//:scripts/requirements-base.txt",
)
use_repo(pip, "pip")

inject_repo(zephyr_patch_file, "pip")
```

## Examples

Examples are located in the `examples/` directory, which contains its own
`MODULE.bazel`. Each subdirectory is a different example project.

To build all of the examples, run the following:

```bash
cd examples
./pw default
```

To build, individual examples specify the Zephyr app target and Zephyr board
platform. For example:
```
bazelisk build //hello_bazel --platforms=@zephyr//boards/tdk/robokit1:same70q21b
bazelisk build //nrf52 --platforms=@zephyr//boards/nordic/nrf52833dk:nrf52833
```

See the `"builds"` in `examples/workflows.json` for an up-to-date list of
commands for building examples. For a detailed breakdown of the examples directory
structure and the distinction between pristine application examples and
build-system integration tests, see the [Examples Guide](examples.md).

For more details on how to define Zephyr apps and boards and how the bazel build
maps to the Zephyr build system and constructs, see the
[User Guide](user_guide.md).