Package: daml-dit-ddit
daml-dit-dditdditis a command line tool that streamlines and automates the
process of building composite artifacts forDaml Hub. A composite artifact is a
collection of multiple single artifacts packaged into aDIT file.
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.Installingdditdditis a Python executable distributed via thePyPIpackage index. Given a
Python installation of version 3.7 or later,dditcan be installed
usingpip3:$pip3installdaml-dit-dditOnce installed, verifydditby launching it without arguments:$ddit
usage:ddit[-h][--verbose]{build,clean,ditversion,genargs,inspect,install,publish,release,run,show,targetname}...

positionalarguments:{build,clean,ditversion,genargs,inspect,install,publish,release,run,show,targetname}subcommandbuildBuildaDITfile.cleanResetsthelocalbuildtargetandvirtualenvironmenttoanemptystate.ditversionPrintthecurrentversionindabl-meta.yamlgenargsWriteatemplateintegrationargfiletostdoutinspectInspectthecontentsofaDITfile.installInstalltheDITfile'sdependenciesintoalocalvirtualenvironment.publishTagandreleasethecurrentDITfile.releaseTagandreleasethecurrentDITfile.runRunthecurrentprojectasanintegration.showVerifyandprintthecurrentmetadatafile.targetnamePrintthebuildtargetfilenametostdout

optionalarguments:-h,--helpshowthishelpmessageandexit--verboseTurnonadditionallogging.2021-06-30T13:20:33-0500[ERROR](ddit)FatalError:Subcommandmissing.dditProject structureIn common with other build tools,dditexposes its interface via a
set of subcommands and operates in project directories with a standard
layout. There are three requirements for additproject 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.yamland a source directory.)dabl-meta.yamlEvery project has adabl-meta.yamlfile at its root. The format of
the file is defined indaml-dit-api, and a typical example
looks like this:catalog:name:openwork-boardversion:3.2.2short_description:OpenWork Boarddescription:A privacy-focused Kanban board.author:Digital Asset (Switzerland) GmbHurl:https://github.com/digital-asset/danbanlicense:Apache-2.0demo_url:https://board.opensaasame.org/tags:[application]icon_file:danban-icon.pngAvailable catalog fields include the following:FieldDescriptionnameMachine-readable name for the project. All DIT files with the same project name are considered to be different versions of the same project.versionThe version number of the projectshort_descriptionA short description of the project, displayed in the App tile on the console.descriptionAn optional long-form description of the project.authorThe name of the author.emailContract e-mail address for project support.urlThe URL to the project's home page,licenseThe name of project's license.demo_urlAn optional link to a live Demonstration instance of the project.source_urlA optional link to the project's source repository.tagsA 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_fileThe filename for the project's icon file. This file can be either aPNGorSVGimage and must be present by that name in the output DIT. By default,dditwill 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 ofddit inspect. These are generally
legacy fields used in earlier versions of Daml Hub. To ensure
compatability,dditwill normalize the contents ofdabl-meta.yamlto include values for these fields (and some of these other fields can
still be specified indabl-meta.yamlfor 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 Projectdditis integrated into theDaml SDK,
and DIT file projects can be colocated in the same directory asdaml.yaml.
If a Daml project is present,dditwill 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 withdditA project can be built withddit 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/dablchathttps://github.com/digital-asset/dablchesshttps://github.com/OpenSaaSame/boardThese are all built using Makefiles that manage the build of
individual artifacts within each project.dditdoes not build user
interfaces, so the Makefile handles that aspect of the build and
delegates todditto manage build, packaging, and release of the DIT
file itself.dditprimarily serves to assemble packages out of
components built by other build processes. To include these sorts of
artifacts into a DIT file,ddit buildhas a--subdeploymentsoption 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 inspectcan 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.$dditinspectdabl-integration-core-0.9.7.dit
Artifacthash:7663d38129c2ed47e921a99713f1ca95285b0a1ff9e0bbad3768363cc3158d15

PackageCatalog:name:dabl-integration-coreversion:0.9.7description:TimerandLoopbackIntegrationsrelease_date:2021-06-22author:DigitalAsset(Switzerland)GmbHurl:Noneemail:Nonelicense:Apache-2.0experimental:Falsedemo_url:Nonesource_url:https://github.com/digital-asset/daml-dit-integration-coretags:['integration']short_description:TheCorePackgroup_id:com.digitalasseticon_file:integration-icon.svg

DamlModel:Name/Version:dabl-integration-core:1.1.1PackageID:779c8ad14dd7c7bce05035bbdf7e374e0a349ac501bc4289246b2eaeaef7f990

IntegrationTypes:loopback-Loopbacktimer-Timerledger_event_log-LedgerEventLogtable-Table

Subdeployments:dabl-integration-core-1.1.1.dar(234742bytes,6c2b1589f5c3083114c78d195af2f1f139661c3cdfb13f4b9f143f9706576f92)Building integrationsIntegration 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 contactDigital Assetfor more information on
deploying custom integration types into Daml Hub.dditwill build an integration DIT file for projects that defineintegration_typesin theirdabl-meta.yamlThis 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 optionalrequirements.txtfile at the root of the
project.Python source for the integrations is stored insrc/.dditprovides 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 thedaml-dit-ifdocumeentation.