Artifact generators are scripts that fetch the latest version of your source code/binary. They do the following:

  1. Find the latest version of your source code/binary
  2. Download it and compote its hashes in various formats
  3. Add its size
  4. Export all the data according to the artifact input/output format

Generator input

Artifact generators get access to the root package structure, which includes the package's name, description, homepage, etc. Inside the root package structure the user can include an additional object for the generator. This is the pattern we use for our first-party generators, so we recommend that you follow it.

For example:

{
    "name": "pkg",
    "my-generator": {
        "data1": "1",
        "data2": "2"
    }
}

Generator output

The output of artifact generators looks like this:

{
    "version": "1.0.0.0",
    "tarball-urls": [
         {
             "size": "12345", // Optional
             "url": "https://example.com/tarball.tar.xz",
             "checksums": {
                 "md5": "da280b49ce0656aab7eb26fdd7288552",
                 "sha1": "ef0991b4e2a92c3d8cf5d450c48b785b1b4a530e",
                 
                 "sha2-224": "bf8df207ca9e829904a5b1d431c69cece29aa52e070e873a1f4077bd",
                 "sha3-224": "0190faf244f46e51cbcc495183da82f06294cf16546c7cc7628e2394",
            
                 "sha2-256": "9ab6ce8c93c2fd7584068d02f05e3877c059268d855dd56f7a0582f38614113e",
                 "sha3-256": "b45e988218d8742a900367835d2d98f7e6d96dd0777d306ce78b83c1891e9a58",
            
                 "sha2-384": "30881641c1aab504e4bed14bad3d19d3cf686908abab844c108d6e827d4af580a35698e1ea7587fbd286d8e4865ef275",
                 "sha3-384": "012a50a9249881aa02e7ae273e558091e0c0f13b4e94449ac7424fd7e71cb901f9336183a75f1f525b630561227aa204",
            
                 "sha2-512": "225852ca74e443f56f08c24924df2b8f6558ad73d1960428defae9324c2c740dd9b83b89ef245cd1a9e4c35b4a9fe7f6ede2cb9d015bc347de32db5a71254f54",
                 "sha3-512": "ebe7514c427ce9679c22395ce23059b14c79085f252874156ff240b7204f3903d3fa2b99d2ba197b378961bdae7768c1aee8501dd9c97e07103d109a6f46f75a",
            
                 "blake2b": "1514386df1d6acc68e018e808297ec67a4eba6320e9ad92a5d557bbed205b045811205aa04dcbb880ae1fd746e39e70821b9229234578068bceaf9e456b27a1b",
                 "blake2s": "9e195354f84a5ff8ead5bd98289722015717608653666eedd3f3329024811e08"
             }
         }
    ],
    "exports": {
        "description": "description",
        "var": "var"
    }
}

Note

The exports object is optional. If it exists and it contains the same variable as one that was defined previously in the package metadata, pkggen uses the value from the package metadata, since it's assumed that it was added there to override the value inside of the exports object.

Note

The blake2b and blake2s checksums are set to 512 and 256 bits respectively, since we assume that most packaging systems will want for them to be of the highest byte size. If you find to be using a packaging system with a variable-size blake2b/s checksum, please create a feature request.

Note

The list of checksums must always contain the results of the following hashing algorithms:

  1. BLAKE2B(512bit)
  2. BLAKE2S(256bit)
  3. SHA3:
    • 224
    • 256
    • 384
    • 512
  4. SHA2:
    • 224
    • 256
    • 384
    • 512
  5. SHA1
  6. MD5

If a packaging system requires the use of a hashing algorithm that is not part of pkggen by default, submit a bug report, or in cases of outdated and insecure hashing algorithms, consider submitting bug reports and feature requests to their project instead.

Examples

Good examples of how an artifact generator looks like are the built-in GitHub and URL generators. You can find them as part of the source code of pkggen.