Publish a package¶

Organise, configure, install dependencies, publish.

Publishing steps¶

A Tatin package separates APL source files from files such as CSS, EXE, DLL and so on. Tatin calls the APL files source and the others assets.

Arrange your files accordingly, e.g.

myproj/
├── assets/
│   ├── config.ini
│   ├── foo.json
│   ├── style.css
│   └── tests.csv
└── source/
    ├── RunTests.aplf
    ├── asc.aplf
    ├── dot.aplo
    ├── mean.aplf
    └── valid8_.aplf

Create a default configuration for your package:
```
]TATIN.PackageConfig path/to/myproj -edit
```
The command prompts you for the essential configuration parameters and writes myproj/apl-package.json.
If your project incorporates other Tatin packages, install them, e.g.
```
]TATIN.InstallPackages aplteam-MarkAPL path/to/myproj
```
]InstallPackages

This will install the dependencies in myproj/packages and write there¹ a file apl-dependencies.txt.
Finally, publish.
```
]TATIN.PublishPackage /path/to/myproj [tatin-test]
```
]PublishPackage

Tatin zips your package and uploads it to the registry. The registry unzips it, validates the configuration, and checks for a LICENSE file. If all is well, the package is stored permanently.

The most common error is a version conflict: a published version cannot be republished. This is by design — it guarantees that any build depending on that version can always be reproduced.

On success, Tatin reports Package published on <URL>.

Dependencies¶

Location¶

Where should your package’s dependencies be installed?

By default, Tatin installs them in a project subfolder packages/.

If you manage your package as a Cider project, Tatin will check the Cider configuration properties dependencies.tatin and dependencies_dev.tatin and install where they say.

If you do not use Cider you can use command options or API function parameters to specify an alternative to packages/.

Unpublished dependencies¶

If you specify a dependency not (yet) published, the server you publish to will not object.

This is because, when several packages are published, there might be mutual – or worse, circular – dependencies between them. Requiring dependencies to be already published would not work in that case.

URL protocols¶

URL protocols (file://, http://, https://) are not acceptable for specifying a dependency of a published package. If you publish a package foo with a dependency goo specified with a URL protocol, the registry will remove the protocol and retain only goo. When Tatin loads foo, it will scan the registries in its search path and use the first goo it finds.

Tatin does allow URL protocols for local development — use them with care.

URL protocols override Tatin’s scan strategy

Normally, when a dependency is required, Tatin scans known registries in order of priority – unless a URL protocol is used.

User-command packages¶

A user-command package has a script that makes it a user command.

The package might look like this:

MyUserCommand/
    APLSource/
        MyUserCommand/        ⍝ Contains the code
        TestData/
        TestCases/
        MyUserCommand.dyalog  ⍝ The user command script
    packages/
        ...
    packages_dev/
        ...
    apl-package.json
    cider.config
    LICENSE
    README

The package configuration specifies

source: "APLSource/MyUserCommand",

which excludes TestData/ and TestCases/ from the published package, but also excludes script MyUserCommand.dyalog – which we need in the package root!

So tell Tatin the package is a user command, and where to find its script. In the package configuration:

userCommandScript: "APLSource/MyUserCommand.dyalog",

This marks the package as a user command. Tatin first installs everything as usual, then moves the script to the root of the package.

The installed package will then consist of:

a folder for the MyUserCommand package
folders for all dependencies
a file apl-buildlist.json
a file apl-dependencies.txt
the user command script MyUserCommand.dyalog

A package must contain code.

If you implement a user command as a single script file (quite possible for a simple command), that would not be true. So, separate the user-command script (with the required Run, List and Help functions) from the ‘real code’ that does the work.

Keeping the real code in the package satisfies the requirement.

Deleting packages¶

A registry’s delete policy controls whether you can delete a package published there:

Any – you may delete any package
JustBetas – you may delete only beta versions
None – you cannot delete any packages at all

Each server-hosted registry publishes its delete policy on its home page.

By default Tatin assumes a subfolder packages/ to contain dependencies. ↩