The SDK Assistant is a command-line tool designed to help you interact with the DAML SDK. It includes commands to help you create projects, run other SDK tools, install and upgrade SDK releases, and view documentation.
Installing the SDK Assistant¶
Refer to Installing the SDK for instructions on how to install the SDK Assistant.
All general SDK Assistant files are stored in
~/.da/. This folder contains the
da binary itself, a global
SDK configuration file called
da.yaml, and the downloaded SDK releases and
related packages. On installation, the SDK Assistant will attempt to set up a
Understanding the SDK Assistant¶
The SDK Assistant is designed to make DAML development as easy and enjoyable as possible by helping with two key tasks:
- Initializing DAML SDK projects so you can use development tools for project-specific application code. All SDK development should be confined within a DAML SDK project.
- Managing DAML SDK releases from Digital Asset by periodically checking for updates. When an update is available, it is automatically downloaded and installed, keeping your SDK instance up to date. SDK releases contain development tools and libraries – the DAML compiler, the DAML Studio IDE, and a DAML ledger, for example.
Because the SDK Assistant controls SDK releases and related tools, it can manage several versions of a tool and ensure that it uses the version compatible with the active project and other running tools. See Managing SDK releases.
Using the SDK Assistant¶
The SDK Assistant is invoked with the
da command in a terminal. If you do not
add any arguments to the command, it will default to display a status message.
da --help command to display a list of valid options and commands:
da --help SDK Assistant - Version Usage: da [-c|--config FILENAME] [-l|--log-level debug|info|warn|error] [--script] [--term-width ARG] [COMMAND] SDK Assistant. Use --help for help. Available options: -h,--help Show this help text -c,--config FILENAME Specify what config file to use. -l,--log-level debug|info|warn|error Set the log level. Default is 'warn'. --script Script mode -- skip auto-upgrades and similar. --term-width ARG Rendering width of the terminal. -v,--version Show version and exit Available commands: status Show SDK environment overview docs Show SDK documentation new Create a new project from template add Add a template to the current project project Manage DAML SDK projects template Manage DAML SDK templates upgrade Upgrade to latest SDK version list List installed SDK versions use Set the default SDK version, downloading it if necessary uninstall Remove DAML SDK versions or the complete DAML SDK start Start a given service restart Restart a given service stop Stop a given service feedback Send us feedback! studio Start DAML Studio in the current project navigator Start Navigator (also runs Sandbox if needed) sandbox Start Sandbox process in current project compile Compile a DAML project into a DAR package path Show the filesystem path of an SDK component run Run the main executable of a package setup Set up SDK environment (e.g. on install or upgrade) subscribe Subscribe for a namespace (of the template repository). unsubscribe Unsubscribe from a namespace (of the template repository). config-help Show config-file help config Query and manage configuration changelog Show the changelog of an SDK version update-info Show SDK Assistant update channel information
To get help for a particular command, use this command:
da <command> --help
da new --help Usage: da new PROJECT_PATH Create a new project Available options: -h,--help Show this help text PROJECT_PATH Path to the new project. Name of the last folder will be the name of the new project.
Developing with the SDK Assistant¶
To begin, create a new DAML SDK project using the SDK Assistant. A project consists
of a folder with a valid
da.yaml file that, among other things, specifies
which SDK release is being used. This is important because the release determines which
versions of DAML and the DAML Sandbox the project code uses.
In the SDK Assistant, create a DA project with this command:
da new <project_path>
da new my-project
This example creates a project folder called
my-project folder that is seeded with a basic folder structure.
Change to the new project directory.
In the project folder, use SDK Assistant functions. For example, if you have Visual Studio Code installed, open DAML Studio for your project using:
Use the following command to start the DAML Sandbox and the Navigator against the current project’s DAML code:
These services will run in the background. To see a list of running services, use this command:
To stop any running services of the current project:
The current SDK functionality is still basic. Future releases will improve and extend the current functionality and features to help you develop automation, UIs, and other types of functionality on top of your DAML application.
Building DAML archives¶
The SDK Assistant can compile your DAML source code into a DAML archive (a
.dar file). To do this, run:
This will compile the source code file set in your
configuration file (see Configuring compilation) and
.dar file in the directory
target with the same name as your
Managing SDK releases¶
The SDK Assistant will automatically check for updates and upgrade itself if there is a new version. This means that you will always have the latest version.
If you are working on several projects that have code that assumes different tool and component versions, you will need to have several SDK releases installed at the same time. Having different SDK releases available ensures all your projects will work without your having to upgrade all of them to use the latest libraries and tools. The SDK Assistant has commands for managing several SDK releases.
- The active release is the one that is currently in use. For example, each DAML SDK project specifies the SDK release to use. When you are in a project, the specified release is the active one.
- The default release is the one that will be used when you start a new project or in other cases when an SDK release is needed and you are not in a project.
To list all installed SDK releases and see which are active and which is the default, use this command:
To change the default release:
da use <release-version>
To upgrade to the latest SDK release manually:
To remove unused old releases:
da uninstall <release-version>
Managing SDK templates¶
You can use the SDK Assistant to subscribe to templates, which are stored under a specific namespace. Often these are DAML templates, but not all of them are. There are two types of template:
- Project templates, which are the starting point for a full project. These give you a folder with its own
- Add-on templates, which are the starting point for a sub-project. These give you a folder that lives inside a DAML SDK project folder. Add-on templates are not always DAML templates.
The Assistant comes with several DAML templates that are pre-made example modules, which show advanced uses of DAML and provide useful library functions.
To list available project templates, run:
To list available add-on templates, run:
da new and
da add may show undocumented or unsupported templates.
To subscribe to a namespace (so you can access the template inside it), run:
da subscribe <namespace>
To unsubscribe (remove from the list of namespaces which are checked if the listing commands are executed), run:
da unsubscribe <namespace>
Once you’ve subscribed to a project template’s namespace, you can start a new project from the project template:
da new <namespace>/<project-template-name> <project-path>
Once you’ve subscribed to an add-on template’s namespace, you can add the add-on template to your project:
da add <namespace>/<add-on-template-name> <target-folder>
For DAML templates, the new DAML files are added to your project inside the
daml folder. To use them in your project, you need to add references to these files in the
daml/Main.daml file with
import statements. This is not done automatically.
Running SDK tools¶
The SDK also comes with some packages that you can run and that can serve as important tools in the development of the project. You can run an executable package with the following command:
da run <package> [-- ARGS]
If you run the command above without the package argument, it will display a message saying that the package is missing and will show a list of all the available packages. The available packages currently are
damlc package is a DAML compiler tool. The compiler functionality is currently intended only for internal use, so it is not described in this documentation.
navigator package contains a browser-based tool that can also be used to interact with the ledger and is described in Navigator.
The SDK Assistant uses a configuration file –
da.yaml– that includes both global configuration and project configuration information. The SDK
da.yaml file is located in the SDK Assistant home folder
~/.da/). Project configuration in this file is ignored. Each project also
da.yaml file, which specifies project configuration and can also
override global configuration properties. To list the properties that can be specified in the configuration file, use this command:
Some tools, like the Navigator, require parties to be configured before it is started.
When using the SDK Assistant to start such services, configure parties in
da.yaml file for the project. The
project.parties property takes a list of
strings. For example:
... project: sdk-version: '0.6.0' scenario: Main:example name: my-project source: daml/Main.daml parties: - OPERATOR - BANK1 - BANK2 - '007'
This can also be formatted in YAML as:
... project: sdk-version: '0.6.0' scenario: Main:example name: my-project source: daml/Main.daml parties: ["OPERATOR", "BANK1", "BANK2", "007"]
DAML compilation is configured with the following
- The name of the project.
- The path to the source code.
- The directory to store generated
.darfiles, the default is
.dar file will be stored in
Uninstalling DAML SDK¶
If for any reason the DAML SDK needs to be removed use:
da uninstall all
This command will ask for confirmation and remove the complete DAML SDK home folder (
~/.da/) and the
da symlink in
/usr/local/bin created upon installation.