How to create a package for use with ATS?

[gmhwxi]

I did various experiments in the past week, trying to create some packages
containing ATS code and then make use of them to support programming with ATS.

I mention as follows some guidelines I gathered based on my own experience.

First, I suggest the following structure for a package:

SATS: containing SATS files
DATS: containing DATS files
TEST: containing some tests for the package, which also serve as a form of documentation
README: saying something about the package
mylibies.dats // may be needed; see below
mydepies.hats // may be needed; see below

######

When is mylibies.dats needed?

######

Say there is a package XYZ and I want to use it.
In my code stored in mycode.dats, I may have lines like
the following one:

staload "$PATSHOMELOCS/XYZ/SATS/somefile.sats"

At the end, when I try to compile mycode.dats into executable,
I need to link to the functions implemented in the DATS files in XYZ/DATS.
This is the place where mylibies.dats comes into play. I can create
a file called the same name mylibies.dats, and store the following line into it:

#include "PATSHOMELOCS/XYZ/mylibies.dats"

Then I can do

patscc mycode.dats mylibies.dats

There can certainly be variations of what is described here, but the basic idea
is the same: XYZ/mylibies.dats allows the user of XYZ to gain access to the functions
implemented in XYZ at link-time.

A good example to study is atscntrb-hx-parcomb, which is a simple package of parsing combinators.

Of course, mylibies.dats is not needed if XYZ contains only function templates.

Sometimes, there is also mylibies.sats for handling the compilation of exceptions.

######

When is mydepies.hats needed?

######

Say we have a package XYZ that contains some function templates. Also, XYZ uses another package
FOO (of some other function templates). In order to compile the templates implemented in XYZ, the compiler
needs to access the code implementing the templates in FOO. This is the place where mydepies.hats
comes into play. Basically, mydepies.hats for XYZ should statically load in all the template implementations
needed for compiling the templates in XYZ.

A good example to study is atscntrb-hx-mygrading, which makes use of atscntrb-hx-csv-parse. When using
atscntrb-hx-mygrading, one typically need to write the following lines:

//
#define
HX_MYGRADING_targetloc
"$PATSHOMELOCS/atscntrb-hx-mygrading"
//
#include "{$HX_MYGRADING}/mydepies.hats"
#staload
MYGRADING = "{$HX_MYGRADING}/SATS/mygrading.sats"
#staload
_(*MYGRADING*) = "{$HX_MYGRADING}/DATS/mygrading.dats"
//

######

So far, things have worked out remarkably well in terms of packaging for ATS via npm.
I thank npm people for the terrific work. Ever since I started using this kind of packaging,
I find it to quickly become indispensable. It is really hard to go back as going back is a bit
like trying to use Haskell without Cabal.

Happy packaging!

######

Cheers,

--Hongwei

[gmhwxi]

A few more guidelines on packaging:

mydepies.dats: upstream linking
mydepies.hats: upstream staloading
mylibies.dats: downstream linking
mylibies.hats: downstream staloading