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 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).