mirror of
https://github.com/digital-asset/daml.git
synced 2024-09-19 16:57:40 +03:00
remove da -> daml upgrade docs (#6100)
The `da` tool has not existed for a while now and it's unlikely any new user will need to know about the upgrade path. I think starting from 1.2.0 it makes sense not to have that documenation around anymore. Note that we do have references to the upgrade page in the release notes, so leaving them as is would break building the documentation. My preference would have been to turn those references into "external" links to the relevant version, but unfortunately, these are versions (`0.12.15` and `0.12.18`) that, for various reasons, we cannot build anymore and do not have in pre-built form. I have therefore decided to change the links in the release notes to link to the latest existing version of that page (which is pretty much what it already did), i.e. specifically link to `1.1.1`. CHANGELOG_BEGIN CHANGELOG_END
This commit is contained in:
Gary Verhaegen
GitHub
parent
e86fbedfd0
commit
26bfab48d7
3
docs/.gitignore
vendored
3
docs/.gitignore
vendored
@ -1,3 +1,2 @@
|
||||
.vscode/settings.json
|
||||
da.yaml
|
||||
/source/app-dev/grpc/proto-docs.rst
|
||||
/source/app-dev/grpc/proto-docs.rst
|
||||
|
||||
@ -1,223 +0,0 @@
|
||||
.. Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
|
||||
.. SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
Moving to the new DAML assistant
|
||||
################################
|
||||
|
||||
We've released a new command-line tool for working with the DAML SDK: DAML Assistant, or ``daml``. Many of its commands are similar to the old SDK Assistant (``da``), but there are some changes:
|
||||
|
||||
- Simplified installation process: ``curl -sSL https://get.daml.com/ | sh`` for Linux and Mac
|
||||
- Overhaul and simplification of templates:
|
||||
|
||||
- ``daml new`` takes arguments in a consistent order:
|
||||
|
||||
- ``daml new proj`` creates a new project named ``proj`` with a skeleton template
|
||||
- ``daml new proj quickstart-java`` creates a new project with the quickstart-java template
|
||||
|
||||
- ``daml new`` templates are built-in to the SDK
|
||||
- Mix-in template mechanism is gone (``da add``)
|
||||
- No more publishing or subscribing of templates on Bintray: use Github and ``git clone`` to distribute templates outside of the SDK
|
||||
|
||||
- Use ``daml build`` to compile your project into a DAR
|
||||
- ``daml start`` components don't run in the background, and you stop them with ``ctrl+c``
|
||||
|
||||
As a result, there are no equivalents to ``da stop`` and ``da restart``
|
||||
|
||||
- No ``da run`` equivalent, but:
|
||||
|
||||
- ``daml sandbox`` is the same as ``da run sandbox --``
|
||||
- ``daml navigator`` is the same as ``da run navigator --``
|
||||
- ``daml damlc`` is the same as ``da run damlc --``
|
||||
- ``daml.yaml`` configuration file replaces ``da.yaml`` - read more about this in the next section
|
||||
|
||||
Migrating a ``da`` project to ``daml``
|
||||
======================================
|
||||
|
||||
Migrating with daml init
|
||||
************************
|
||||
|
||||
You can migrate an existing project using the ``daml init`` command. To use it, go to the project root on the command line and run ``daml init``. This will create a ``daml.yaml`` file based on ``da.yaml``.
|
||||
|
||||
Some things to keep in mind when using ``daml init`` to migrate projects:
|
||||
|
||||
- If your project uses an SDK version prior to 0.12.15, the generated ``daml.yaml`` will use SDK version 0.12.15 instead. Support for previous SDK versions in the new assistant is limited.
|
||||
|
||||
- ``daml.yaml`` adds ``exposed-modules`` and ``dependencies`` fields, which are needed for ``daml build``. Depending on your DAML project, may have to adjust these fields in the generated ``daml.yaml``.
|
||||
|
||||
Migrating manually
|
||||
******************
|
||||
|
||||
To migrate the project manually:
|
||||
|
||||
1. Upgrade your project to SDK version 0.12.15 or later.
|
||||
2. Convert your project's ``da.yaml`` file into a ``daml.yaml`` file.
|
||||
|
||||
The two files are very similar: ``daml.yaml`` is the ``project`` section of ``da.yaml``, plus some additional packaging information. Here is an example of a ``daml.yaml`` file, from the quickstart-java template:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
sdk-version: 0.12.14
|
||||
name: my_project
|
||||
source: daml
|
||||
scenario: Main:setup
|
||||
parties:
|
||||
- Alice
|
||||
- Bob
|
||||
- USD_Bank
|
||||
- EUR_Bank
|
||||
version: 1.0.0
|
||||
exposed-modules:
|
||||
- Main
|
||||
dependencies:
|
||||
- daml-prim
|
||||
- daml-stdlib
|
||||
|
||||
Here is the corresponding ``da.yaml`` file:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
project:
|
||||
sdk-version: 0.12.12
|
||||
scenario: Main:setup
|
||||
name: foobar
|
||||
source: daml
|
||||
parties:
|
||||
- Alice
|
||||
- Bob
|
||||
- USD_Bank
|
||||
- EUR_Bank
|
||||
version: 2
|
||||
|
||||
The extra fields in ``daml.yaml`` are related to the new packaging functionality in ``damlc``. When you build a DAML project with ``daml build`` (or ``daml start``) it creates a ``.dar`` package from your project inside the ``dist/`` folder. (You can supply a different target location by passing the ``-o`` option.) To create the package properly, the new config file ``daml.yaml`` needs the following additional fields that were not present in ``da.yaml``:
|
||||
|
||||
- ``version``: The version number for the DAML project, which becomes the version number for the compiled package.
|
||||
- ``exposed-modules``: When the ``.dar`` file is built, this determines what modules are exposed for users of the package.
|
||||
- ``dependencies``: The DAML packages that this project depends on. ``daml-prim`` and ``daml-stdlib`` together give access to the basic definitions of DAML - **you should add them both as dependencies**. Additional dependencies can only be added by giving the path to the ``.dar`` file of the other package.
|
||||
|
||||
You can now use ``daml`` commands with your project.
|
||||
|
||||
Switching from old commands to new ones
|
||||
=======================================
|
||||
|
||||
This section goes through the ``da`` commands, and gives the ``daml`` equivalent where there is one.
|
||||
|
||||
Managing versions and config
|
||||
****************************
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Old command
|
||||
- Purpose
|
||||
- New equivalent
|
||||
* - ``da setup``
|
||||
- Initialize the SDK
|
||||
- No longer needed: this is handled by the installer
|
||||
* - ``da upgrade``
|
||||
- Upgrade SDK version
|
||||
- ``daml install <version>``
|
||||
* - ``da list``
|
||||
- List installed SDK versions
|
||||
- ``daml version``
|
||||
* - ``da use``
|
||||
- Set the default SDK version
|
||||
- No direct equivalent; you now set the new SDK version (``sdk-version: X.Y.Z``) in your project config file (``daml.yaml``) manually
|
||||
* - ``da config``
|
||||
- Query and manage config
|
||||
- No equivalent: view and edit your config files directly
|
||||
* - ``da uninstall``
|
||||
- Uninstall the SDK
|
||||
- Currently no equivalent for this
|
||||
* - ``da update-info``
|
||||
- Show assistant update channel information
|
||||
- No longer needed
|
||||
|
||||
Running components
|
||||
******************
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Old command
|
||||
- Purpose
|
||||
- New equivalent
|
||||
* - ``da start``
|
||||
- Start Navigator and Sandbox
|
||||
- ``daml start``
|
||||
* - ``da stop``
|
||||
- Stop running Navigator and Sandbox
|
||||
- ``ctrl+c``
|
||||
* - ``da restart``
|
||||
- Shut down and restart Navigator and Sandbox
|
||||
- ``ctrl+c`` and ``daml start``
|
||||
* - ``da studio``
|
||||
- Launch DAML Studio
|
||||
- ``daml studio``
|
||||
* - ``da navigator``
|
||||
- Launch Navigator
|
||||
- No direct equivalent; ``daml navigator`` is equivalent to ``da run navigator``
|
||||
* - ``da sandbox``
|
||||
- Launch Sandbox
|
||||
- No direct equivalent; ``daml sandbox`` is equivalent to ``da run sandbox``
|
||||
* - ``da compile``
|
||||
- Compile a DAML project into a .dar file
|
||||
- ``daml build``
|
||||
* - ``da run <component>``
|
||||
- Run an SDK component
|
||||
- ``daml navigator``, ``daml sandbox``, etc as above
|
||||
* - ``da path <component>``
|
||||
- Show the path to an SDK component
|
||||
- No equivalent
|
||||
* - ``da status``
|
||||
- Show a list of running services
|
||||
- No longer needed: components no longer run in the background
|
||||
|
||||
Managing templates and projects
|
||||
*******************************
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Old command
|
||||
- Purpose
|
||||
- New equivalent
|
||||
* - ``da template``
|
||||
- Manage SDK templates
|
||||
- No longer needed: use ``git clone`` for templates instead
|
||||
* - ``da project new``
|
||||
- Create an SDK project
|
||||
- ``daml new``, or use ``git clone``
|
||||
* - ``da project add``
|
||||
- Add a template to the current project
|
||||
- No longer needed: use ``git clone`` instead
|
||||
* - ``da new``
|
||||
- Create a new project from template
|
||||
- ``daml new <target path> <name of template>``
|
||||
* - ``da subscribe``
|
||||
- Subscribe to a template namespace
|
||||
- No longer needed: use ``git clone`` instead
|
||||
* - ``da unsubscribe``
|
||||
- Unsubscribe from a template namespace
|
||||
- No longer needed: use ``git clone`` instead
|
||||
|
||||
Docs and feedback
|
||||
*****************
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - Old command
|
||||
- Purpose
|
||||
- New equivalent
|
||||
* - ``da docs``
|
||||
- Display the documentation
|
||||
- No longer needed: you can access the docs at `docs.daml.com <https://docs.daml.com/>`__, which includes a PDF download for offline use
|
||||
* - ``da feedback``
|
||||
- Send us feedback
|
||||
- No longer needed: see :doc:`/support/support` for how to give feedback.
|
||||
* - ``da config-help``
|
||||
- Show help about config files
|
||||
- No longer needed: config files are documented on this page
|
||||
* - ``da changelog``
|
||||
- Show release notes
|
||||
- No longer needed: see the :doc:`/support/release-notes`
|
||||
@ -3398,7 +3398,7 @@ SDK tools
|
||||
|
||||
- **DAML Assistant**: We've built a new and improved version of the SDK assistant, replacing ``da`` commands with ``daml`` commands. The documentation is updated to use the new assistant in this release.
|
||||
|
||||
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`.
|
||||
For a full guide to what's changed and how to migrate, see `Moving to the new DAML assistant <https://docs.daml.com/1.1.1/support/new-assistant.html>`__. To read about how to use the new ``daml`` Assistant, see :doc:`/tools/assistant`.
|
||||
|
||||
DAML
|
||||
~~~~
|
||||
@ -3606,7 +3606,7 @@ SQL Extractor
|
||||
To try it out, download the installer from `GitHub releases <https://github.com/digital-asset/daml/releases>`__. The Windows SDK uses the new ``daml`` command-line which will soon also
|
||||
become the default on Linux and MacOS.
|
||||
|
||||
Documentation is still in progress, but you can see the :doc:`Migration guide </support/new-assistant>` and the `pull request for the updated documentation <https://github.com/digital-asset/daml/pull/740>`__.
|
||||
Documentation is still in progress, but you can see `Moving to the new DAML assistant <https://docs.daml.com/1.1.1/support/new-assistant.html>`__ and the `pull request for the updated documentation <https://github.com/digital-asset/daml/pull/740>`__.
|
||||
- **DAML Standard Library**: Added ``fromListWith`` and ``merge`` to ``DA.TextMap``.
|
||||
- **DAML Standard Library**: Deprecated ``DA.Map`` and ``DA.Set``. Use the new ``DA.Next.Map`` and ``DA.Next.Set`` instead.
|
||||
- **Ledger API**: Added three new methods to the :ref:`CommandService <com.daml.ledger.api.v1.commandservice>`:
|
||||
@ -3853,8 +3853,3 @@ No user-facing changes.
|
||||
- **Ledger API**: Version 1.4.0 has full support for transaction trees.
|
||||
- **Sandbox**: Implements Ledger API version 1.4.0.
|
||||
- **Java Bindings**: Examples updated to use version 2.5.2 which implements Ledger API version 1.4.0.
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
/support/new-assistant
|
||||
|
||||
@ -32,11 +32,6 @@ DAML Assistant (``daml``)
|
||||
|
||||
Note that you need to update your `project config file <#configuration-files>` to use the new version.
|
||||
|
||||
Moving to the ``daml`` assistant
|
||||
********************************
|
||||
|
||||
To move your projects to use ``daml``, and see the difference between ``da`` commands and ``daml`` commands, read the :doc:`/support/new-assistant`.
|
||||
|
||||
Full help for commands
|
||||
**********************
|
||||
|
||||
@ -80,7 +75,7 @@ The project config file ``daml.yaml`` must be in the root of your DAML project d
|
||||
|
||||
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``.
|
||||
|
||||
``daml init`` creates a ``daml.yaml`` in an existing folder, so ``daml`` knows it's a project folder. It incorporates info from ``da.yaml`` in the generated ``daml.yaml``, if ``da.yaml`` is available (see :doc:`/support/new-assistant`).
|
||||
``daml init`` creates a ``daml.yaml`` in an existing folder, so ``daml`` knows it's a project folder.
|
||||
|
||||
``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:
|
||||
|
||||
|
||||
@ -47,9 +47,6 @@ EOF
|
||||
## special cases we should work to remove
|
||||
|
||||
# quickstart-java template
|
||||
# right now, uses the preexisting quickstart-java rule and replaces the
|
||||
# da.yaml template with a daml.yaml template; in the future, move
|
||||
# everything into //templates/quickstart-java and avoid untar, rm here
|
||||
tar xf $(location //docs:quickstart-java.tar.gz) --strip-components=1 -C $$OUT/quickstart-java
|
||||
|
||||
# quickstart-scala template
|
||||
|
||||
Loading…
Reference in New Issue
Block a user