Using developer environments¶

Developer environments are preconfigured workspaces that provide everything required for contributing to the Agent code base, testing changes and building release artifacts. Usually, these are images that run using a container orchestrator like Docker or Podman.

This tutorial will walk through how to use such environments with the dda env dev command group.

Note

This tutorial assumes you have already set up the development requirements.

Overview¶

A developer environment may be used either as an ephemeral or persistent workspace. Multiple environments can be used concurrently, with each using a different checkout of the Agent repository.

To get an idea of upcoming interactions, run dda env dev and you should see the following output.

$ dda env dev

 Usage: dda env dev [OPTIONS] COMMAND [ARGS]...

╭─ Options ────────────────────────────────────────────────────────────╮
│ --help  -h  Show this message and exit.                              │
╰──────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────╮
│ cache   Manage the cache                                             │
│ code    Open a code editor for the developer environment             │
│ gui     Access a developer environment through a graphical interface │
│ remove  Remove a developer environment                               │
│ run     Run a command within a developer environment                 │
│ shell   Spawn a shell within a developer environment                 │
│ show    Show the available developer environments                    │
│ start   Start a developer environment                                │
│ status  Check the status of a developer environment                  │
│ stop    Stop a developer environment                                 │
╰──────────────────────────────────────────────────────────────────────╯

Environment selection¶

When an environment is started, there are two options that permanently influence the environment until it is removed.

The --id option sets the identifier that subsequent commands use to target the environment. All commands use the word default if no ID is provided. Environments of different types can have the same ID.
The -t/--type option selects the type of developer environment. The following types are available:
- linux-container - This runs the Linux developer environment and is the default type on non-Windows systems.
More types will be added in the future. All non-macOS cloud environments will simply use the developer environment containers.

Note

The default type on Windows is windows-container but that is not yet implemented. As a temporary workaround, use the linux-container type with the -t/--type start command option or configure dda to use it as the default type for developer environments with the following command.

dda config set env.dev.default-type linux-container

Starting environments¶

You can start an environment with the dda env dev start command. All developer environment types support the following options.

Repository location¶

You may select where the code resides when starting an environment.

Local checkout¶

The default behavior assumes a local checkout of the Agent repository. Clone the repo if you haven't already.

git clone https://github.com/DataDog/datadog-agent.git

Then enter the cloned directory and run the following command to start an environment.

dda env dev start

Warning

There are two downsides to this approach.

It's not possible to have multiple environments using a separate checkout of the Agent repository i.e. you inherit the limitations of a usual Git checkout.
Bind mounts may experience performance issues, particularly for Git operations.

Remote clone¶

You can start an environment with a fresh clone of the Agent repository by passing the --clone flag.

dda env dev start --clone

You can also configure dda to always clone repositories for developer environments with the following command.

dda config set env.dev.clone-repos true

This will perform a shallow clone of the default branch, main.

Repository selection¶

Note

This functionality has no effect when using a local checkout.

The -r/--repo option selects the Datadog repositories to clone and may be supplied multiple times. By default, only the datadog-agent repository is chosen.

dda env dev start -r datadog-agent -r integrations-core

The first selected repository becomes the default location for the environment such as when running commands or entering a shell.

Type-specific options¶

Each developer environment type has additional options that are only available when using that type. For example, the linux-container type supports a --no-pull flag to disable the automatic pull of the latest image.

The help text displays options for the default type. In order to see options for a specific type, use the -t/--type option before the help flag like in the following example.

dda env dev start -t linux-container -h

Environment status¶

You can check the status of an environment by running the following command.

dda env dev status

This shows the environment's state and any extra information that may be useful for debugging.

Environments have the following possible states.

started - The environment is running.
stopped - The environment is stopped.
starting - The environment is starting.
stopping - The environment is stopping.
error - The environment is in an error state.
nonexistent - The environment does not exist.
unknown - The environment is in an unknown state.

Entering a shell¶

You can spawn a shell within an environment by running the following command.

dda env dev shell

This opens a shell within the first defined repository.

Preparing for development¶

Run the following command in the environment's shell to install some remaining dependencies.

dda inv install-tools

If you're using a remote clone, some builds may fail due to the shallow cloning. To acquire all Git history, run the following command.

git fetch --unshallow

Testing¶

Verify your setup by running some unit tests with the following command.

dda inv test --targets=pkg/aggregator

Editing code¶

Exit the environment's shell or open a new session and run the following command locally.

dda env dev code

This opens one of the supported editors for the repository selected with the -r/--repo option, defaulting to the first defined repository. The editor may take a few moments to start up the first time it opens in an environment.

The editor may be selected with the -e/--editor option or by configuring dda to use a specific editor for developer environments by default with the following command.

dda config set env.dev.editor cursor

To test functionality, create a file test.txt at the root of the repository and save it.

Running commands¶

You can run commands within an environment without entering a shell by passing arbitrary arguments to the dda env dev run command locally. Confirm the file test.txt was created by running the following command.

dda env dev run -- ls -l test.txt

The repository in which to run the command is determined by the -r/--repo option, defaulting to the first defined repository.

Building¶

Let's build the default Agent by running the following command locally.

dda env dev run -- dda inv agent.build --build-exclude=systemd

Confirm that the binary was successfully built by running the following command.

dda env dev run -- ls -l bin/agent/agent

If you're using a local checkout you should also see that binary on your local machine. This strategy extends to other build artifacts so you could, for example, build the Debian package and install it on an arbitrary machine running Ubuntu.

Caveat

Environments using a remote clone have no easier way to share build artifacts with your local machine than to use the docker cp command. This is a temporary limitation.

Stopping environments¶

You can stop an environment by running the following command.

dda env dev stop

This stops the environment but does not remove it. Environments can be started again at any time from a stopped state. When this happens, the start command only accepts options for environment selection.

Removing environments¶

Environments can be removed by running the following command.

dda env dev remove

This removes the environment and all associated data.

Tip

The stop command accepts a -r/--remove option to remove the environment after stopping it, useful for ephemeral environments.

dda env dev stop -r