# daml-dit-ddit
`ddit` is a command line tool that streamlines and automates the
process of building composite artifacts for
[Daml Hub](https://hub.daml.com/). A composite artifact is a
collection of multiple single artifacts packaged into a
[DIT file](https://github.com/digital-asset/daml-dit-api).
Artifacts in a DIT file can include Daml Models and Triggers,
Python Bots, Custom UI code, and Integration Types. Daml Hub
uses DIT files to package sample applications, libraries, and
integrations into a single deployable entity.
# Installing `ddit`
`ddit` is a Python executable distributed via the
[PyPI](https://pypi.org/project/daml-dit-ddit/) package index. Given a
Python installation of version 3.7 or later, `ddit` can be installed
using `pip3`:
```sh
$ pip3 install daml-dit-ddit
```
Once installed, verify `ddit` by launching it without arguments:
```sh
$ ddit
usage: ddit [-h] [--verbose] {build,clean,ditversion,genargs,inspect,install,publish,release,run,show,targetname} ...
positional arguments:
{build,clean,ditversion,genargs,inspect,install,publish,release,run,show,targetname}
subcommand
build Build a DIT file.
clean Resets the local build target and virtual environment to an empty state.
ditversion Print the current version in dabl-meta.yaml
genargs Write a template integration argfile to stdout
inspect Inspect the contents of a DIT file.
install Install the DIT file's dependencies into a local virtual environment.
publish Tag and release the current DIT file.
release Tag and release the current DIT file.
run Run the current project as an integration.
show Verify and print the current metadata file.
targetname Print the build target filename to stdout
optional arguments:
-h, --help show this help message and exit
--verbose Turn on additional logging.
2021-06-30T13:20:33-0500 [ERROR] (ddit) Fatal Error: Subcommand missing.
```
# `ddit` Project structure
In common with other build tools, `ddit` exposes its interface via a
set of subcommands and operates in project directories with a standard
layout. There are three requirements for a `ddit` project directory:
* `dabl-meta.yaml` - A metadata file at the root of the project that
contains information on the contents of the project. (Name, version,
URL links, etc.)
* `pkg/` - A subdirectory containing resources and files that will be
included in the output DIT.
* An optional Daml model build, also at the project root. (`daml.yaml`
and a source directory.)
## `dabl-meta.yaml`
Every project has a `dabl-meta.yaml` file at its root. The format of
the file is defined in [`daml-dit-api`](https://github.com/digital-asset/daml-dit-api/blob/master/daml_dit_api/package_metadata.py), and a typical example
looks like this:
```yaml
catalog:
name: openwork-board
version: 3.2.2
short_description: OpenWork Board
description: A privacy-focused Kanban board.
author: Digital Asset (Switzerland) GmbH
url: https://github.com/digital-asset/danban
license: Apache-2.0
demo_url: https://board.opensaasame.org/
tags: [application]
icon_file: danban-icon.png
```
Available catalog fields include the following:
| Field | Description |
|-------|-------------|
| `name` | Machine-readable name for the project. All DIT files with the same project name are considered to be different versions of the same project. |
| `version` | The version number of the project |
| `short_description` | A short description of the project, displayed in the App tile on the console.|
| `description` | An optional long-form description of the project. |
| `author` | The name of the author. |
| `email` | Contract e-mail address for project support. |
| `url` | The URL to the project's home page, |
| `license` | The name of project's license. |
| `demo_url` | An optional link to a live Demonstration instance of the project. |
| `source_url` | A optional link to the project's source repository. |
| `tags` | A list of tags associated with the project. These can be used to query specific sets of artifacts from the arcade for display in the console. |
| `icon_file` | The filename for the project's icon file. This file can be either a `PNG` or `SVG` image and must be present by that name in the output DIT. By default, `ddit` will look for the icon file in the project root and include from there if found. |
Note that there are a few other catalog fields listed in the API
source and shown in the output of `ddit inspect`. These are generally
legacy fields used in earlier versions of Daml Hub. To ensure
compatability, `ddit` will normalize the contents of `dabl-meta.yaml`
to include values for these fields (and some of these other fields can
still be specified in `dabl-meta.yaml` for their original purpose.)
These other fields (the ones not listed above) should be considered
deprecated for future use.
## `pkg/`
This is an optional directory that contains other resources to be
includued in the output DIT.
## Daml Project
`ddit` is integrated into the
[Daml SDK]((https://docs.daml.com/getting-started/installation.html)),
and DIT file projects can be colocated in the same directory as `daml.yaml`.
If a Daml project is present, `ddit` will automatically manage the build
of the resultant DAR and include it in the output DIT. For projects that
need more control over the DAR build process, the automatic DAR build
can be disabled with `--skip-dar-build`.
# Building a project with `ddit`
A project can be built with `ddit build`. For examples of what this
looks like in practice, please see one of several sample applications
available through Daml Hub:
- <https://github.com/digital-asset/dablchat>
- <https://github.com/digital-asset/dablchess>
- <https://github.com/OpenSaaSame/board>
These are all built using Makefiles that manage the build of
individual artifacts within each project. `ddit` does not build user
interfaces, so the Makefile handles that aspect of the build and
delegates to `ddit` to manage build, packaging, and release of the DIT
file itself. `ddit` primarily serves to assemble packages out of
components built by other build processes. To include these sorts of
artifacts into a DIT file, `ddit build` has a `--subdeployments`
option that takes a list of other artifacts that will be included in
the DIT file and deployed as part of the DIT file deployment.
# Inspecting a DIT file.
To facilitate management of DIT files, `ddit inspect` can be used to
view a summary of the contents of a DIT file. This includes relevent
artifact hashes, information on the associated Daml model, and catalog
information for the file.
```sh
$ ddit inspect dabl-integration-core-0.9.7.dit
Artifact hash: 7663d38129c2ed47e921a99713f1ca95285b0a1ff9e0bbad3768363cc3158d15
Package Catalog:
name : dabl-integration-core
version : 0.9.7
description : Timer and Loopback Integrations
release_date : 2021-06-22
author : Digital Asset (Switzerland) GmbH
url : None
email : None
license : Apache-2.0
experimental : False
demo_url : None
source_url : https://github.com/digital-asset/daml-dit-integration-core
tags : ['integration']
short_description : The Core Pack
group_id : com.digitalasset
icon_file : integration-icon.svg
Daml Model:
Name/Version: dabl-integration-core:1.1.1
Package ID: 779c8ad14dd7c7bce05035bbdf7e374e0a349ac501bc4289246b2eaeaef7f990
Integration Types:
loopback - Loopback
timer - Timer
ledger_event_log - Ledger Event Log
table - Table
Subdeployments:
dabl-integration-core-1.1.1.dar (234742 bytes, 6c2b1589f5c3083114c78d195af2f1f139661c3cdfb13f4b9f143f9706576f92)
```
# Building integrations
Integration DIT files differ from applications in that they contain
code that runs inside Daml Hub with elevated permissions that enable
them to access external network connections. Integrations are the only
deployable code that has this permission. Because of these elevated
runtime rights, specific user permissions are required to deploy
integration DIT files to Daml Hub. Please contact
[Digital Asset](https://discuss.daml.com/) for more information on
deploying custom integration types into Daml Hub.
`ddit` will build an integration DIT file for projects that define
`integration_types` in their `dabl-meta.yaml` This section specifies
the integration types contained in the DIT file. When building as an
integration, the DIT file project directory gains some of the traits
of a Python project.
* Python dependencies to be included in the output DIT can be
specified in an optional `requirements.txt` file at the root of the
project.
* Python source for the integrations is stored in `src/`.
`ddit` provides several additional utility commands to assist
developing an integration:
* `ddit genargs` - This generates a template argument file for the
integration to be run locally. Once generated, the template should be
edited to include the desired configuration values.
* `ddit run` - This runs an integration locally against a locally
running ledger.
For more details on implementing an integration, see the
[`daml-dit-if`](https://github.com/digital-asset/daml-dit-if)
documeentation.
Raw data
{
"_id": null,
"home_page": "https://github.com/digital-asset/daml-dit-ddit",
"name": "daml-dit-ddit",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "daml,blockchain,dlt,distributed ledger,digital asset",
"author": "Daml Hub Team",
"author_email": "daml-hub-team@digitalasset.com",
"download_url": "https://files.pythonhosted.org/packages/43/71/01e3f2134f01568c6bda7003121cade30de212d950f6883e441af32f3d50/daml_dit_ddit-0.7.0.tar.gz",
"platform": null,
"description": "# daml-dit-ddit\n\n`ddit` is a command line tool that streamlines and automates the\nprocess of building composite artifacts for\n[Daml Hub](https://hub.daml.com/). A composite artifact is a\ncollection of multiple single artifacts packaged into a\n[DIT file](https://github.com/digital-asset/daml-dit-api).\nArtifacts in a DIT file can include Daml Models and Triggers,\nPython Bots, Custom UI code, and Integration Types. Daml Hub\nuses DIT files to package sample applications, libraries, and\nintegrations into a single deployable entity.\n\n# Installing `ddit`\n\n`ddit` is a Python executable distributed via the\n[PyPI](https://pypi.org/project/daml-dit-ddit/) package index. Given a\nPython installation of version 3.7 or later, `ddit` can be installed\nusing `pip3`:\n\n```sh\n$ pip3 install daml-dit-ddit\n```\n\nOnce installed, verify `ddit` by launching it without arguments:\n\n```sh\n$ ddit\nusage: ddit [-h] [--verbose] {build,clean,ditversion,genargs,inspect,install,publish,release,run,show,targetname} ...\n\npositional arguments:\n {build,clean,ditversion,genargs,inspect,install,publish,release,run,show,targetname}\n subcommand\n build Build a DIT file.\n clean Resets the local build target and virtual environment to an empty state.\n ditversion Print the current version in dabl-meta.yaml\n genargs Write a template integration argfile to stdout\n inspect Inspect the contents of a DIT file.\n install Install the DIT file's dependencies into a local virtual environment.\n publish Tag and release the current DIT file.\n release Tag and release the current DIT file.\n run Run the current project as an integration.\n show Verify and print the current metadata file.\n targetname Print the build target filename to stdout\n\noptional arguments:\n -h, --help show this help message and exit\n --verbose Turn on additional logging.\n2021-06-30T13:20:33-0500 [ERROR] (ddit) Fatal Error: Subcommand missing.\n```\n\n# `ddit` Project structure\n\nIn common with other build tools, `ddit` exposes its interface via a\nset of subcommands and operates in project directories with a standard\nlayout. There are three requirements for a `ddit` project directory:\n\n* `dabl-meta.yaml` - A metadata file at the root of the project that\n contains information on the contents of the project. (Name, version,\n URL links, etc.)\n* `pkg/` - A subdirectory containing resources and files that will be\n included in the output DIT.\n* An optional Daml model build, also at the project root. (`daml.yaml`\n and a source directory.)\n\n## `dabl-meta.yaml`\n\nEvery project has a `dabl-meta.yaml` file at its root. The format of\nthe file is defined in [`daml-dit-api`](https://github.com/digital-asset/daml-dit-api/blob/master/daml_dit_api/package_metadata.py), and a typical example\nlooks like this:\n\n```yaml\ncatalog:\n name: openwork-board\n version: 3.2.2\n short_description: OpenWork Board\n description: A privacy-focused Kanban board.\n author: Digital Asset (Switzerland) GmbH\n url: https://github.com/digital-asset/danban\n license: Apache-2.0\n demo_url: https://board.opensaasame.org/\n tags: [application]\n icon_file: danban-icon.png\n```\n\nAvailable catalog fields include the following:\n\n| Field | Description |\n|-------|-------------|\n| `name` | Machine-readable name for the project. All DIT files with the same project name are considered to be different versions of the same project. |\n| `version` | The version number of the project |\n| `short_description` | A short description of the project, displayed in the App tile on the console.|\n| `description` | An optional long-form description of the project. |\n| `author` | The name of the author. |\n| `email` | Contract e-mail address for project support. |\n| `url` | The URL to the project's home page, |\n| `license` | The name of project's license. |\n| `demo_url` | An optional link to a live Demonstration instance of the project. |\n| `source_url` | A optional link to the project's source repository. |\n| `tags` | A list of tags associated with the project. These can be used to query specific sets of artifacts from the arcade for display in the console. |\n| `icon_file` | The filename for the project's icon file. This file can be either a `PNG` or `SVG` image and must be present by that name in the output DIT. By default, `ddit` will look for the icon file in the project root and include from there if found. |\n\nNote that there are a few other catalog fields listed in the API\nsource and shown in the output of `ddit inspect`. These are generally\nlegacy fields used in earlier versions of Daml Hub. To ensure\ncompatability, `ddit` will normalize the contents of `dabl-meta.yaml`\nto include values for these fields (and some of these other fields can\nstill be specified in `dabl-meta.yaml` for their original purpose.)\nThese other fields (the ones not listed above) should be considered\ndeprecated for future use.\n\n## `pkg/`\n\nThis is an optional directory that contains other resources to be\nincludued in the output DIT. \n\n## Daml Project\n\n`ddit` is integrated into the\n[Daml SDK]((https://docs.daml.com/getting-started/installation.html)), \nand DIT file projects can be colocated in the same directory as `daml.yaml`.\nIf a Daml project is present, `ddit` will automatically manage the build\nof the resultant DAR and include it in the output DIT. For projects that\nneed more control over the DAR build process, the automatic DAR build \ncan be disabled with `--skip-dar-build`.\n\n# Building a project with `ddit`\n\nA project can be built with `ddit build`. For examples of what this\nlooks like in practice, please see one of several sample applications\navailable through Daml Hub:\n\n- <https://github.com/digital-asset/dablchat>\n- <https://github.com/digital-asset/dablchess>\n- <https://github.com/OpenSaaSame/board>\n\nThese are all built using Makefiles that manage the build of\nindividual artifacts within each project. `ddit` does not build user\ninterfaces, so the Makefile handles that aspect of the build and\ndelegates to `ddit` to manage build, packaging, and release of the DIT\nfile itself. `ddit` primarily serves to assemble packages out of\ncomponents built by other build processes. To include these sorts of\nartifacts into a DIT file, `ddit build` has a `--subdeployments`\noption that takes a list of other artifacts that will be included in\nthe DIT file and deployed as part of the DIT file deployment.\n\n# Inspecting a DIT file.\n\nTo facilitate management of DIT files, `ddit inspect` can be used to\nview a summary of the contents of a DIT file. This includes relevent\nartifact hashes, information on the associated Daml model, and catalog\ninformation for the file.\n\n```sh\n$ ddit inspect dabl-integration-core-0.9.7.dit\nArtifact hash: 7663d38129c2ed47e921a99713f1ca95285b0a1ff9e0bbad3768363cc3158d15\n\nPackage Catalog:\n name : dabl-integration-core\n version : 0.9.7\n description : Timer and Loopback Integrations\n release_date : 2021-06-22\n author : Digital Asset (Switzerland) GmbH\n url : None\n email : None\n license : Apache-2.0\n experimental : False\n demo_url : None\n source_url : https://github.com/digital-asset/daml-dit-integration-core\n tags : ['integration']\n short_description : The Core Pack\n group_id : com.digitalasset\n icon_file : integration-icon.svg\n\nDaml Model:\n Name/Version: dabl-integration-core:1.1.1\n Package ID: 779c8ad14dd7c7bce05035bbdf7e374e0a349ac501bc4289246b2eaeaef7f990\n\nIntegration Types:\n loopback - Loopback\n timer - Timer\n ledger_event_log - Ledger Event Log\n table - Table\n\nSubdeployments:\n dabl-integration-core-1.1.1.dar (234742 bytes, 6c2b1589f5c3083114c78d195af2f1f139661c3cdfb13f4b9f143f9706576f92)\n```\n\n# Building integrations\n\nIntegration DIT files differ from applications in that they contain\ncode that runs inside Daml Hub with elevated permissions that enable\nthem to access external network connections. Integrations are the only\ndeployable code that has this permission. Because of these elevated\nruntime rights, specific user permissions are required to deploy\nintegration DIT files to Daml Hub. Please contact\n[Digital Asset](https://discuss.daml.com/) for more information on\ndeploying custom integration types into Daml Hub.\n\n`ddit` will build an integration DIT file for projects that define\n`integration_types` in their `dabl-meta.yaml` This section specifies\nthe integration types contained in the DIT file. When building as an\nintegration, the DIT file project directory gains some of the traits\nof a Python project.\n\n* Python dependencies to be included in the output DIT can be\n specified in an optional `requirements.txt` file at the root of the\n project.\n* Python source for the integrations is stored in `src/`.\n\n`ddit` provides several additional utility commands to assist\ndeveloping an integration:\n\n* `ddit genargs` - This generates a template argument file for the\n integration to be run locally. Once generated, the template should be\n edited to include the desired configuration values.\n* `ddit run` - This runs an integration locally against a locally\n running ledger.\n\n For more details on implementing an integration, see the\n[`daml-dit-if`](https://github.com/digital-asset/daml-dit-if)\ndocumeentation.\n",
"bugtrack_url": null,
"license": "",
"summary": "Daml Hub DIT File Tool",
"version": "0.7.0",
"project_urls": {
"Homepage": "https://github.com/digital-asset/daml-dit-ddit",
"Repository": "https://github.com/digital-asset/daml-dit-ddit"
},
"split_keywords": [
"daml",
"blockchain",
"dlt",
"distributed ledger",
"digital asset"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c7f7df64ac46043410aca4a2e849aa821fcce2c63c118cf184684c791d34d3ca",
"md5": "7feb443917440a4dde3a82660a778b30",
"sha256": "938dec17a1ac025a97d6332df67bbf9612f89b7380a13e46a69ffd436007e8b0"
},
"downloads": -1,
"filename": "daml_dit_ddit-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7feb443917440a4dde3a82660a778b30",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 25841,
"upload_time": "2023-12-07T14:15:42",
"upload_time_iso_8601": "2023-12-07T14:15:42.835543Z",
"url": "https://files.pythonhosted.org/packages/c7/f7/df64ac46043410aca4a2e849aa821fcce2c63c118cf184684c791d34d3ca/daml_dit_ddit-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "437101e3f2134f01568c6bda7003121cade30de212d950f6883e441af32f3d50",
"md5": "942591b1b303a06e20701013d996f98e",
"sha256": "f985d7368a72df0cf37ade2f7395635763c85946dc984a920251498f4dab3ad4"
},
"downloads": -1,
"filename": "daml_dit_ddit-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "942591b1b303a06e20701013d996f98e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 23120,
"upload_time": "2023-12-07T14:15:46",
"upload_time_iso_8601": "2023-12-07T14:15:46.050126Z",
"url": "https://files.pythonhosted.org/packages/43/71/01e3f2134f01568c6bda7003121cade30de212d950f6883e441af32f3d50/daml_dit_ddit-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-07 14:15:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "digital-asset",
"github_project": "daml-dit-ddit",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "daml-dit-ddit"
}
JSON
