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. ///
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 │
╰──────────────────────────────────────────────────────────────────────╯
When an environment is started, there are two options that permanently influence the environment until it is removed.
-
The
--idoption sets the identifier that subsequent commands use to target the environment. All commands use the worddefaultif no ID is provided. Environments of different types can have the same ID. -
The
-t/--typeoption 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-config] dda to use it as the default type for developer environments with the following command.
dda config set env.dev.default-type linux-container
///
You can start an environment with the dda env dev start command. All developer environment types support the following options.
You may select where the code resides when starting an environment.
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. ///
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-config] 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.
/// 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.
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
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.
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.
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
Verify your setup by running some unit tests with the following command.
dda inv test --targets=pkg/aggregator
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-config] 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.
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.
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.
/// note | 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.
///
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.
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
///