Publish a package

Organise, configure, install dependencies, publish.

Get started

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

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

Tatin allows you to identify a package with a URL protocol, either the file:// protocol for a local resource or http:// or https:// for a remote one.

Useful as these are for local development, neither is acceptable for specifying a dependency of a published package.

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.

Use URL protocols for local development only, and only with care.

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.

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. ↩