digital-asset/daml
1
1
Fork 0
mirror of https://github.com/digital-asset/daml.git synced 2024-09-17 15:57:21 +03:00
Code Issues Projects Releases Wiki Activity

Full documentation for the new assistant (#740)

Browse Source 
* First draft of new assistant docs

* Quick pass to fix up references

* Apply suggestions from code review

Co-Authored-By: bethaitman <bethaitman@users.noreply.github.com>

* Apply suggestions from code review

* Fix links

* Fill out assistant docs somewhat

* Update docs/source/tools/extractor.rst

* Update quickstart guide from #720

* Fixes

* daml new changes

* Update docs/source/getting-started/quickstart.rst

Co-Authored-By: bethaitman <bethaitman@users.noreply.github.com>

* Fix build

* Fix todos about protobuf

* Final tidying up

* Add installer link

* Apply suggestions from code review

Co-Authored-By: bethaitman <bethaitman@users.noreply.github.com>

* A couple of corrections

* Add release note

* Fix release notes

* AAAAAAAAAARGH
This commit is contained in:
Beth Aitman 2019-05-13 18:33:59 +02:00 committed by mergify[bot]
parent 50bcb853ea
commit 8c8bd5e6b9
12 changed files with 156 additions and 351 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/.gitignore vendored
View File

@ -1,2 +1,3 @@
.vscode/settings.json
da.yaml
da.yaml
/source/app-dev/grpc/proto-docs.rst

2
docs/source/app-dev/bindings-java/codegen.rst
View File

@ -18,7 +18,7 @@ You can download the `latest version <https://bintray.com/api/v1/content/digital
* the downloaded Java codegen jar file, eg. 10x.y.z
* the dependency to :ref:`bindings-java <daml-codegen-java-compiling>`, eg. 10x.y.z
* the ``sdk-version`` attribute in the :ref:`da.yaml <da-yaml-configuration>` file, eg. x.y.z
* the ``sdk-version`` attribute in the :ref:`daml.yaml <daml-yaml-configuration>` file, eg. x.y.z
.. _daml-codegen-java-running:

6
docs/source/app-dev/grpc/index.rst
View File

@ -12,18 +12,16 @@ The Ledger API using gRPC
If you want to write an application for the ledger API in other languages, you'll need to use `gRPC <https://grpc.io>`__ directly.
If you're not familiar with gRPC, we strongly recommend following the `gRPC quickstart <https://grpc.io/docs/quickstart/>`__ and `gRPC tutorials <https://grpc.io/docs/tutorials/>`__. You need an understanding of gRPC before you can use this version of the Ledger API.
If you're not familiar with gRPC and protobuf, we strongly recommend following the `gRPC quickstart <https://grpc.io/docs/quickstart/>`__ and `gRPC tutorials <https://grpc.io/docs/tutorials/>`__. This documentation is written assuming you already have an understanding of gRPC.
Getting started
***************
To add all of the necessary protobuf files to a project, run ``da project add ledger-api-protos``.
You can either get the protobufs `from Bintray here <https://bintray.com/digitalassetsdk/DigitalAssetSDK/sdk-components#files/com%2Fdigitalasset%2Fledger-api-protos>`__, or from the ``daml`` repository `here <https://github.com/digital-asset/daml/tree/master/ledger-api/grpc-definitions>`__.
Protobuf reference documentation
********************************
.. TODO brief explanation of protos.
For full details of all of the Ledger API services and their RPC methods, see :doc:`/app-dev/grpc/proto-docs`.
Example project

12
docs/source/daml/daml-studio.rst
View File

@ -14,12 +14,14 @@ To install DAML Studio, :doc:`install the SDK </getting-started/installation>`.
Creating your first DAML file
*****************************
1. Start Visual Studio Code. To start it in the current project, use the ``da studio`` command.
Alternatively you can simply start VS Code as you would normally start any application.
1. Start DAML Studio by running ``daml studio`` in the current project.
2. Check that the DAML Studio extension is installed by first clicking on
the Extensions icon at the bottom of the VS Code sidebar, and
then clicking on the DAML Studio extension that should be listed on the pane.
This command starts Visual Studio Code and (if needs be) installs the DAML Studio extension, or upgrades it to the latest version.
2. Make sure the DAML Studio extension is installed:
1. Click on the Extensions icon at the bottom of the VS Code sidebar.
2. Click on the DAML Studio extension that should be listed on the pane.
.. image:: daml-studio/images/daml_studio_extension_view.png

43
docs/source/getting-started/installation.rst
View File

@ -14,42 +14,23 @@ You need to install:
1. `Visual Studio Code <https://code.visualstudio.com/download>`_.
2. `JDK 8 or greater <http://www.oracle.com/technetwork/java/javase/downloads/index.html>`_.
2. Set up the SDK Assistant
***************************
2. Install the SDK
*******************
The SDK is distributed via a command-line tool called the :doc:`SDK Assistant </tools/assistant>`. To install the SDK Assistant:
Mac and Linux
=============
#. Download the latest installer for your platform:
To install the SDK on Mac or Linux:
- .. rst-class:: cta-alt
`Linux installer <https://cta-redirect.hubspot.com/cta/redirect/5388578/05b2410e-fba4-4d42-b125-f7fd2dc3ba5d>`_
.. raw:: html
1. Run::
<!--HubSpot Call-to-Action Code --><span class="hs-cta-wrapper" id="hs-cta-wrapper-05b2410e-fba4-4d42-b125-f7fd2dc3ba5d"><span class="hs-cta-node hs-cta-05b2410e-fba4-4d42-b125-f7fd2dc3ba5d" id="hs-cta-05b2410e-fba4-4d42-b125-f7fd2dc3ba5d"><!--[if lte IE 8]><div id="hs-cta-ie-element"></div><![endif]--><a href="https://cta-redirect.hubspot.com/cta/redirect/5388578/05b2410e-fba4-4d42-b125-f7fd2dc3ba5d" target="_blank" ><img class="hs-cta-img" id="hs-cta-img-05b2410e-fba4-4d42-b125-f7fd2dc3ba5d" style="border-width:0px;" src="https://no-cache.hubspot.com/cta/default/5388578/05b2410e-fba4-4d42-b125-f7fd2dc3ba5d.png" alt="Linux installer"/></a></span><script charset="utf-8" src="https://js.hscta.net/cta/current.js"></script><script type="text/javascript"> hbspt.cta.load(5388578, '05b2410e-fba4-4d42-b125-f7fd2dc3ba5d', {}); </script></span><!-- end HubSpot Call-to-Action Code -->
curl -sSL https://get.daml.com/ | sh
2. If prompted, add ``~/.daml/bin`` to your PATH.
- .. rst-class:: cta-alt
`Mac installer <https://cta-redirect.hubspot.com/cta/redirect/5388578/1b93ea71-77c6-4e0e-adbb-de072226d474>`_
.. raw:: html
Windows
=======
<!--HubSpot Call-to-Action Code --><span class="hs-cta-wrapper" id="hs-cta-wrapper-1b93ea71-77c6-4e0e-adbb-de072226d474"><span class="hs-cta-node hs-cta-1b93ea71-77c6-4e0e-adbb-de072226d474" id="hs-cta-1b93ea71-77c6-4e0e-adbb-de072226d474"><!--[if lte IE 8]><div id="hs-cta-ie-element"></div><![endif]--><a href="https://cta-redirect.hubspot.com/cta/redirect/5388578/1b93ea71-77c6-4e0e-adbb-de072226d474" target="_blank" ><img class="hs-cta-img" id="hs-cta-img-1b93ea71-77c6-4e0e-adbb-de072226d474" style="border-width:0px;" src="https://no-cache.hubspot.com/cta/default/5388578/1b93ea71-77c6-4e0e-adbb-de072226d474.png" alt="Mac installer"/></a></span><script charset="utf-8" src="https://js.hscta.net/cta/current.js"></script><script type="text/javascript"> hbspt.cta.load(5388578, '1b93ea71-77c6-4e0e-adbb-de072226d474', {}); </script></span><!-- end HubSpot Call-to-Action Code -->
- Windows installer coming soon - `sign up to be notified <https://hub.daml.com/sdk/windows>`_
The SDK is distributed under the :download:`Apache 2.0 license </LICENSE>` (:download:`NOTICES </NOTICES>`).
#. Run the installer:
.. code::
sh ./da-cli-<version>.run
#. Follow the instructions in the output to update your ``PATH``.
#. Run ``da setup``, which will download and install the SDK.
To install the SDK on Windows, download and run the installer from `github.com/digital-asset/daml/releases/latest <https://github.com/digital-asset/daml/releases/latest>`__.
.. _setup-maven-project:
@ -67,5 +48,5 @@ Next steps
- Follow the :doc:`quickstart guide <quickstart>`.
- Read the :doc:`introduction <introduction>` page.
- Use ``da --help`` to see all the commands that the SDK Assistant provides.
- Use ``daml --help`` to see all the commands that the DAML assistant (``daml``) provides.
- If you run into any problems, :doc:`use the support page </support/support>` to get in touch with us.

31
docs/source/getting-started/quickstart.rst
View File

@ -25,11 +25,11 @@ On this page:
Download the quickstart application
***********************************
You can get the quickstart application as an :ref:`SDK template <cli-managing-templates>`:
You can get the quickstart application using the DAML assistant (``daml``):
#. Run ``da new quickstart``
#. Run ``daml new quickstart quickstart-java``
This loads the entire application into a folder called ``quickstart``.
This creates the ``quickstart-java`` application into a new folder called ``quickstart``.
#. Run ``cd quickstart`` to change into the new directory.
Folder structure
@ -40,7 +40,7 @@ The project contains the following files:
.. code-block:: none
.
├── da.yaml
├── daml.yaml
├── daml
│   ├── Iou.daml
│   ├── IouTrade.daml
@ -57,11 +57,10 @@ The project contains the following files:
│   └── digitalasset
│   └── quickstart
│   └── iou
│   ├── Iou.java
│   └── IouMain.java
└── ui-backend.conf
- ``da.yaml`` is a DAML project definition file consumed by some CLI commands. It will not be used in this guide.
- ``daml.yaml`` is a DAML project config file used by the SDK to find out how to build the DAML project and how to run it.
- ``daml`` contains the :ref:`DAML code <quickstart-daml>` specifying the contract model for the ledger.
- ``daml/Tests`` contains :ref:`test scenarios <quickstart-scenarios>` for the DAML model.
- ``frontend-config.js`` and ``ui-backend.conf`` are configuration files for the :ref:`Navigator <quickstart-navigator>` frontend.
@ -114,7 +113,7 @@ Run the application using prototyping tools
In this section, you will run the quickstart application and get introduced to the main tools for prototyping DAML:
#. To compile the DAML model, run ``da run damlc -- package daml/Main.daml target/daml/iou``
#. To compile the DAML model, run ``daml build -o target/daml/iou.dar``
This creates a DAR package called ``target/daml/iou.dar``. The output should look like this:
@ -124,7 +123,7 @@ In this section, you will run the quickstart application and get introduced to t
.. _quickstart-sandbox:
#. To run the :doc:`sandbox </tools/sandbox>` (a lightweight local version of the ledger), run ``da run sandbox -- --scenario Main:setup target/daml/*``
#. To run the :doc:`sandbox </tools/sandbox>` (a lightweight local version of the ledger), run ``daml sandbox --scenario Main:setup target/daml/iou.dar``
The output should look like this:
@ -138,14 +137,10 @@ In this section, you will run the quickstart application and get introduced to t
_\ \/ _ `/ _ \/ _ / _ \/ _ \\ \ /
/___/\_,_/_//_/\_,_/_.__/\___/_\_\
Initialized sandbox version 100.12.1 with ledger-id = sandbox-5e12e502-817e-41f9-ad40-1c57b8845f9d, port = 6865, dar file = DamlPackageContainer(List(target/daml/iou.dar),false), time mode = Static, ledger = in-memory, daml-engine = {}
Initialized Static time provider, starting from 1970-01-01T00:00:00Z
DAML LF Engine supports LF versions: 1.0, 0; Transaction versions: 1; Value versions: 1
Starting plainText server
listening on localhost:6865
Initialized sandbox version 100.12.10 with ledger-id = sandbox-5e12e502-817e-41f9-ad40-1c57b8845f9d, port = 6865, dar file = DamlPackageContainer(List(target/daml/iou.dar),false), time mode = Static, ledger = in-memory, daml-engine = {}
The sandbox is now running, and you can access its :doc:`ledger API </app-dev/index>` on port ``6865``.
.. note::
The parameter ``--scenario Main:setup`` loaded the sandbox ledger with some initial data. Only the sandbox has this prototyping feature - it's not available on the full ledger server. More on :ref:`scenarios <quickstart-scenarios>` later.
@ -153,7 +148,7 @@ In this section, you will run the quickstart application and get introduced to t
.. _quickstart-navigator:
#. Open a new terminal window and navigate to your project directory.
#. Start the :doc:`Navigator </tools/navigator/index>`, a browser-based leger front-end, by running ``da run navigator -- server``
#. Start the :doc:`Navigator </tools/navigator/index>`, a browser-based leger front-end, by running ``daml navigator server``
The Navigator automatically connects the sandbox. You can access it on port ``4000``.
@ -268,7 +263,7 @@ Develop with DAML Studio
Take a look at the DAML that specifies the contract model in the quickstart application. The core template is ``Iou``.
#. Open :doc:`DAML Studio </daml/daml-studio>`, a DAML IDE based on VS Code, by running ``da studio`` from the root of your project.
#. Open :doc:`DAML Studio </daml/daml-studio>`, a DAML IDE based on VS Code, by running ``daml studio`` from the root of your project.
#. Using the explorer on the left, open ``daml/Iou.daml``.
The first two lines specify language version and module name:
@ -469,7 +464,7 @@ The ``submit`` function used in this scenario tries to perform a transaction and
.. Interact with the ledger through the command line
*************************************************
All interaction with the DA ledger, be it sandbox or full ledger server, happens via the :doc:`Ledger API </app-dev/index>`. It is based on `gRPC <https://grpc.io/>`_.
All interaction with the DA ledger, be it sandbox or full ledger server, happens via the :doc:`Ledger API </app-dev/index>``. It is based on `gRPC <https://grpc.io/>`_.
The Navigator uses this API, as will any :ref:`custom integration <quickstart-application>`.

4
docs/source/support/release-notes.rst
View File

@ -78,7 +78,9 @@ Java Bindings
- **SDK**: The Windows installer no longer requires elevated privileges.
- **DAML Assistant**: The assistant handles network failures gracefully.
- **DAML Assistant**: We've built a new and improved version of the SDK assistant, replacing ``da`` commands with ``daml`` commands.
For a full guide to what's changed and how to migrate, see :doc:`/support/new-assistant`. To read about how to use the new ``daml`` Assistant, see :doc:`/tools/assistant`.
.. _release-0-12-16:

368
docs/source/tools/assistant.rst
View File

@ -1,331 +1,159 @@
.. Copyright (c) 2019 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
SDK Assistant
#############
DAML Assistant (``daml``)
#########################
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.
``daml`` is a command-line tool that does a lot of useful things related to the SDK. Using ``daml``, you can:
Installing the SDK Assistant
****************************
- Create new DAML projects: ``daml new <path to create project in>``
- Compile a DAML project: ``daml build``
Refer to :doc:`/getting-started/installation` for instructions on how to install the SDK Assistant.
This builds the DAML project according to the project config file ``daml.yaml`` (see `Configuration files`_ below).
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
symlink in ``/usr/local/bin``.
In particular, it will download and install the specified version of the SDK (the ``sdk-version`` field in ``daml.yaml``) if missing, and use that SDK version to resolve dependencies and compile the DAML project.
.. CARL: Do we want to add info on what happens if the symlink is not set up?
- Launch the tools in the SDK:
Understanding the SDK Assistant
*******************************
- Launch :doc:`DAML Studio </daml/daml-studio>`: ``daml studio``
- Launch :doc:`Sandbox </tools/sandbox>` and :doc:`Navigator </tools/navigator/index>` together: ``daml start``
- Launch Sandbox: ``daml sandbox``
- Launch Navigator: ``daml navigator``
- Launch :doc:`Extractor </tools/extractor>`: ``daml extractor``
The SDK Assistant is designed to make DAML development as easy and
enjoyable as possible by helping with two key tasks:
- Install new SDK versions manually: ``daml install <version>``
* **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.
Note that you need to update your `project config file <#configuration-files>` to use the new version.
* **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.
Moving to the ``daml`` assistant
********************************
.. note:: 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 :ref:`assistant-manual-managing-releases`.
To move your projects to use ``daml``, and see the difference between ``da`` commands and ``daml`` commands, read the :doc:`/support/new-assistant`.
Using the SDK Assistant
***********************
Full help for commands
**********************
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.
To see information about any command, run it with ``--help``.
Use the ``da --help`` command to display a list of valid options and commands::
.. _daml-yaml-configuration:
da --help
Configuration files
*******************
SDK Assistant - Version
The DAML assistant and the DAML SDK are configured using two files:
Usage: da [-c|--config FILENAME] [-l|--log-level debug|info|warn|error]
[--script] [--term-width ARG] [COMMAND]
SDK Assistant. Use --help for help.
- The global config file, one per installation, which controls some options regarding SDK installation and updates
- The project config file, one per DAML project, which controls how the DAML SDK builds and interacts with the project
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
Global config file (``daml-config.yaml``)
=========================================
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
The global config file ``daml-config.yaml`` is in the ``daml`` home directory (``~/.daml`` on Linux and Mac, ``C:/Users/<user>/AppData/Roaming/daml`` on Windows). It controls options related to SDK version installation and upgrades.
To get help for a particular command, use this command::
By default it's blank, and you usually won't need to edit it. It recognizes the following options:
da <command> --help
- ``auto-install``: whether ``daml`` automatically installs a missing SDK version when it is required (defaults to ``true``)
- ``update-check``: how often ``daml`` will check for new versions of the SDK, in seconds (default to ``86400``, i.e. once a day)
**Example**::
This setting is only used to inform you when an update is available.
Set ``update-check: <number>`` to check for new versions every N seconds. Set ``update-check: never`` to never check for new versions.
da new --help
Here is an example ``daml-config.yaml``:
Usage: da new PROJECT_PATH
Create a new project
.. code-block:: yaml
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.
auto-install: true
update-check: 86400
Developing with the SDK Assistant
*********************************
Project config file (``daml.yaml``)
===================================
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.
The project config file ``daml.yaml`` must be in the root of your DAML project directory. It controls how the DAML project is built and how tools like Sandbox and Navigator interact with it.
In the SDK
Assistant, create a DA project with this command::
The existence of a ``daml.yaml`` file is what tells ``daml`` that this directory contains a DAML project, and lets you use project-aware commands like ``daml build`` and ``daml start``.
da new <project_path>
``daml new`` creates a skeleton application in a new project folder, which includes a config file. For example, ``daml new my_project`` creates a new folder ``my_project`` with a project config file ``daml.yaml`` like this:
**Example**::
.. code-block:: yaml
da new my-project
sdk-version: __VERSION__
name: __PROJECT_NAME__
source: daml/Main.daml
scenario: Main:setup
parties:
- Alice
- Bob
version: 1.0.0
exposed-modules:
- Main
dependencies:
- daml-prim
- daml-stdlib
This example creates a project folder called ``my-project`` folder that is seeded with a basic folder structure.
Here is what each field means:
Change to the new project directory.
- ``sdk-version``: the SDK version that this project uses.
**Example**::
The assistant automatically downloads and installs this version if needed (see the ``auto-install`` setting in the global config). We recommend keeping this up to date with the latest stable release of the SDK.
cd my-project
The assistant will warn you when it is time to update this setting (see the ``update-check`` setting in the global config to control how often it checks, or to disable this check entirely).
- ``name``: the name of the project. This determines the filename of the ``.dar`` file compiled by ``daml build``.
- ``source``: the location of your main DAML source code file, relative to the project root.
- ``scenario``: the name of the scenario to run when using ``daml start``.
- ``parties``: the parties to display in the Navigator when using ``daml start``.
- ``version``: the project version.
- ``exposed-modules``: the DAML modules that are exposed by this project, which can be imported in other projects.
- ``dependencies``: the dependencies of this project.
In the project folder, use SDK Assistant functions. For example, if you have Visual Studio Code installed, open DAML Studio for your project using::
da studio
Use the following command to start the DAML Sandbox and the Navigator against
the current project's DAML code::
da start
These services will run in the background. To see a list of running services, use this command::
da status
To stop any running services of the current project::
da stop
To restart::
da restart
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.
.. TODO (@robin-da) document the dependency syntax
.. _assistant-manual-building-dars:
Building DAML archives
Building DAML projects
**********************
The SDK Assistant can compile your DAML source code into a DAML archive (a
``.dar`` file). To do this, run::
To compile your DAML source code into a DAML archive (a ``.dar`` file), run::
da compile
daml build
This will compile the source code file set in your ``da.yaml``
configuration file (see :ref:`assistant-manual-configuring-compilation`) and
generate a ``.dar`` file in the directory ``target`` with the same name as your
project.
You can control the build by changing your project's ``daml.yaml``:
``sdk-version``
The SDK version to use for building the project.
``name``
The name of the project.
``source``
The path to the source code.
The generated ``.dar`` file is created in ``dist/${name}.dar`` by default. To override the default location, pass the ``-o`` argument to ``daml build``::
daml build -o path/to/darfile.dar
.. _assistant-manual-managing-releases:
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.
In general the ``daml`` assistant will install versions and guide you when you need to update SDK versions or project settings. If you disable ``auto-install`` and ``update-check`` in the global config file, you will have to manage SDK releases manually.
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.
To download and install the latest stable SDK release and update the assistant, run::
- 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.
daml install latest --activate
- 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.
Remove the ``--activate`` flag if you only want to install the latest release without updating the ``daml`` assistant in the process. If it is already installed, you can force reinstallation by passing the ``--force`` flag. See ``daml install --help`` for a full list of options.
To list all installed SDK releases and see which are active and which is the default, use this command::
To install the SDK release specified in the project config, run::
da list
daml install project
To change the default release::
To install a specific SDK version, for example version ``0.13.0``, run::
da use <release-version>
daml install 0.13.0
To upgrade to the latest SDK release manually::
Rarely, you might need to install an SDK release from a downloaded SDK release tarball. **This is an advanced feature**: you should only ever perform this on an SDK release tarball that is released through the official ``digital-asset/daml`` github repository. Otherwise your ``daml`` installation may become inconsistent with everyone else's. To do this, run::
da upgrade
daml install path-to-tarball.tar.gz
To remove unused old releases::
da uninstall <release-version>
.. _cli-managing-templates:
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 ``da.yaml`` file.
- 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::
da new
To list available add-on templates, run::
da add
.. note:: ``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`` and ``navigator``.
The ``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.
The ``navigator`` package contains a browser-based tool that can also be used to interact with the ledger and is described in :doc:`/tools/navigator/index`.
.. _da-yaml-configuration:
da.yaml configuration
*********************
The SDK Assistant uses a configuration file -- ``da.yaml``-- that includes both global configuration and project configuration information. The SDK
Assistant global ``da.yaml`` file is located in the SDK Assistant home folder
(``~/.da/``). Project configuration in this file is ignored. Each project also
has a ``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::
da config-help
Configuring parties
===================
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
the ``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"]
.. _assistant-manual-configuring-compilation:
Configuring compilation
=======================
DAML compilation is configured with the following ``project`` variables:
``project.name``
The name of the project.
``project.source``
The path to the source code.
``project.output-path``
The directory to store generated ``.dar`` files, the default is ``target``.
The generated ``.dar`` file will be stored in
``${project.output-path}/${project.name}.dar``.
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.

14
docs/source/tools/extractor.rst
View File

@ -32,7 +32,7 @@ Prerequisites:
Once you have the prerequisites, you can start the Extractor like this::
$ da run extractor -- --help
$ daml extractor --help
Trying it out
*************
@ -48,7 +48,7 @@ This example extracts:
.. code-block:: none
$ da run extractor -- postgresql --user postgres --connecturl jdbc:postgresql:daml_export --party Scrooge_McDuck -h 192.168.1.12 -p 6865 --to head
$ daml extractor postgresql --user postgres --connecturl jdbc:postgresql:daml_export --party Scrooge_McDuck -h 192.168.1.12 -p 6865 --to head
This terminates after reaching the transaction which was the latest at the time the Extractor started streaming.
@ -59,7 +59,7 @@ Running the Extractor
The basic command to run the Extractor is::
$ da run extractor -- [options]
$ daml extractor [options]
For what options to use, see the next sections.
@ -87,13 +87,13 @@ This example connects to a PostgreSQL instance running on ``localhost`` on the d
.. code-block:: none
$ da run extractor -- postgres --connecturl jdbc:postgresql:daml_export --user postgres --party [party]
$ daml extractor postgres --connecturl jdbc:postgresql:daml_export --user postgres --party [party]
This example connects to a database on host ``192.168.1.12``, listening on port ``5432``. The database is called ``daml_export``, and the user and password used for authentication are ``daml_exporter`` and ``ExamplePassword``
.. code-block:: none
$ da run extractor -- postgres --connecturl jdbc:postgresql://192.168.1.12:5432/daml_export --user daml_exporter --password ExamplePassword --party [party]
$ daml extractor postgres --connecturl jdbc:postgresql://192.168.1.12:5432/daml_export --user daml_exporter --password ExamplePassword --party [party]
Full list of options
********************
@ -257,9 +257,7 @@ These types are translated to `JSON types <https://json-schema.org/understanding
Examples of output
******************
The following examples show you what output you should expect.
The examples use the default built-in SDK project which you get by running ``$ da new [project_name]``. The Sandbox has already run the scenarios of the DAML model which created two transactions: one creating a ``Main:RightOfUseOffer`` and one accepting it, thus archiving the original contract and creating a new ``Main:RightOfUseAgreement`` contract. We also added a new offer manually.
The following examples show you what output you should expect. The Sandbox has already run the scenarios of a DAML model that created two transactions: one creating a ``Main:RightOfUseOffer`` and one accepting it, thus archiving the original contract and creating a new ``Main:RightOfUseAgreement`` contract. We also added a new offer manually.
This is how the ``transaction`` table looks after extracting data from the ledger:

8
docs/source/tools/navigator/console.rst
View File

@ -23,7 +23,7 @@ Try out the Navigator Console on the Quickstart
With the sandbox running the :doc:`quickstart application </getting-started/quickstart>`
#. To start the shell, run ``da run navigator -- console localhost 6865``
#. To start the shell, run ``daml navigator console localhost 6865``
This connects Navigator Console to the sandbox, which is still running.
@ -124,11 +124,11 @@ To run Navigator Console:
1. Open a terminal window and navigate to your DAML SDK project folder.
2. If the Sandbox isn't already running, run it with the command ``da start``.
2. If the Sandbox isn't already running, run it with the command ``daml start``.
The sandbox prints out the port on which it is running - by default, port ``6865``.
3. Run ``da run navigator -- console localhost 6865``.
3. Run ``daml navigator console localhost 6865``.
Replace ``6865`` by the port reported by the sandbox, if necessary.
When Navigator Console starts, it displays a welcome message::
@ -491,4 +491,4 @@ To run Navigator against a secured Digital Asset Ledger, configure TLS certifica
Details of these parameters are explained in the command line help::
da run navigator -- --help
daml navigator --help

6
docs/source/tools/navigator/index.rst
View File

@ -23,12 +23,12 @@ Installing and starting Navigator
Navigator ships with the DAML SDK. To launch it:
1. Start Navigator via a terminal window running :doc:`SDK Assistant </tools/assistant>` by typing ``da start``
1. Start Navigator via a terminal window running :doc:`SDK Assistant </tools/assistant>` by typing ``daml start``
2. The Navigator web-app is automatically started in your browser. If it fails to start,
open a browser window and point it to the Navigator URL
When running ``da start`` you will see the Navigator URL. By default it will be `<http://localhost:7500/>`_. However, if port ``7500`` is taken, a different port will be picked.
When running ``daml start`` you will see the Navigator URL. By default it will be `<http://localhost:7500/>`_.
.. note:: Navigator is compatible with these browsers: Safari, Chrome, or
Firefox.
@ -387,4 +387,4 @@ To run Navigator against a secured Digital Asset Ledger,
configure TLS certificates using the ``--pem``, ``--crt``, and ``--cacrt`` command line parameters.
Details of these parameters are explained in the command line help::
da run navigator -- --help
daml navigator --help

10
docs/source/tools/sandbox.rst
View File

@ -6,15 +6,15 @@
DAML Sandbox
############
The DAML Sandbox, or Sandbox for short, is a simple ledger implementation that enables rapid application prototyping by simulating the Digital Asset Distributed Ledger.
The DAML Sandbox, or Sandbox for short, is a simple ledger implementation that enables rapid application prototyping by simulating a Digital Asset Distributed Ledger.
You can start DAML Sandbox together with :doc:`Navigator </tools/navigator/index>` using the ``da start`` command in a DAML SDK project. This command will compile the DAML file and its dependencies as specified in the ``da.yaml``. It will then launch Sandbox passing the just obtained DAR packages. Sandbox will also be given the name of the startup scenario specified in the project's ``da.yaml``. Finally, it launches the navigator connecting it to the running Sandbox.
You can start Sandbox together with :doc:`Navigator </tools/navigator/index>` using the ``daml start`` command in a DAML SDK project. This command will compile the DAML file and its dependencies as specified in the ``daml.yaml``. It will then launch Sandbox passing the just obtained DAR packages. Sandbox will also be given the name of the startup scenario specified in the project's ``daml.yaml``. Finally, it launches the navigator connecting it to the running Sandbox.
It is possible to execute the Sandbox launching step in isolation by typing ``da sandbox``.
It is possible to execute the Sandbox launching step in isolation by typing ``daml sandbox``.
Sandbox can also be run manually as in this example::
$ da run sandbox -- Main.dar --scenario Main:example
$ daml sandbox Main.dar --scenario Main:example
____ ____
/ __/__ ____ ___/ / / ___ __ __
@ -24,7 +24,7 @@ Sandbox can also be run manually as in this example::
Initialized Static time provider, starting from 1970-01-01T00:00:00Z
listening on localhost:6865
Here, ``da run sandbox --`` tells the SDK Assistant to run ``sandbox`` from the active SDK release and pass it any arguments that follow. The example passes the DAR file to load (``Main.dar``) and the optional ``--scenario`` flag tells Sandbox to run the ``Main:example`` scenario on startup. The scenario must be fully qualified; here ``Main`` is the module and ``example`` is the name of the scenario, separated by a ``:``. The scenario is used for testing and development; it is not run in production.
Here, ``daml sandbox `` tells the SDK Assistant to run ``sandbox`` from the active SDK release and pass it any arguments that follow. The example passes the DAR file to load (``Main.dar``) and the optional ``--scenario`` flag tells Sandbox to run the ``Main:example`` scenario on startup. The scenario must be fully qualified; here ``Main`` is the module and ``example`` is the name of the scenario, separated by a ``:``. The scenario is used for testing and development; it is not run in production.
Running with persistence