Halyde Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Server-side functionality ======
<WRAP important>
This is for Argentum 2, which is included with Halyde 3.0.0+. For the original Argentum, see [[ag1|Argentum 1]].
</WRAP>

===== Master configuration file =====

The master configuration file is located at ``/ag2.json`` in the repository. It contains the bulk of the package information. It is in JSON format. Here is an example of how it could look like:

<code json>
{
  "test-package-name": {
    "type": "package",
    "version": "X.X.X",
    "description": "Your package description goes here.",
    "dependencies": [
      "dependency1",
      "dependency2=1.2.3"
    ],
    "conflicts": [
      "conflict1",
      "conflict2"
    ],
    "mainDirectory": "packages/packageName",
    "files": [
      "file1",
      "halyde/apps/file2",
    ],
    "directories": [
      "packageDir",
      "packageDir/something"
    ],
    "config": [
      "/packageDir/something/config.json"
    ],
    "scripts": {
      "pre-install": "extra/pre-install.lua",
      "post-install": "extra/post-install.lua"
    }
  }
}
</code>

//Note that you may only use lowercase letters, numbers and dashes (``-``) in package names.//

  * ``test-package-name`` is your package's name;
  * ``type`` is the entry's type (in this case ``package``);
  * ``version`` is set to your package's version;
  * ``description`` is a brief description of your package (optional);
  * ``dependencies`` is a list of packages your package depends on (optional) ([[avs|Advanced Versioning Syntax]] may be used here);
  * ``conflicts`` is a list of packages your package conflicts with and cannot be installed alongside (optional) ([[avs|Advanced Versioning Syntax]] may be used here);
  * ``mainDirectory`` is somewhat like a root directory in which all of your package's files are contained in the repository. For example, when downloading ``file1.txt`` for a package that has ``mainDirectory`` set to ``some/directory``, the file will be downloaded from ``some/directory/file1.txt``, but it will be placed in ``/file1.txt`` in the user's system. This is useful for multi-package repositories where two packages can provide different files in the same location. (optional);
  * ``files`` is a list of files that will be downloaded when installing your package relative to the ``mainDirectory`` (optional);
  * ``directories`` is a list of directories that will be created when installing your package relative to the ``mainDirectory`` (optional);
  * ``config`` is a list of config files for your package. They will be created upon installation, but not changed upon updating. When removing the package, the user will be asked whether to remove the config files or not (optional);
  * ``scripts`` is for scripts that will be run before/after installation/update of your package (optional):
      * ``pre-install`` is the path of the script that will be run before installing/updating your package relative to the ``mainDirectory`` (optional);
      * ``post-install`` is the path of the script that will be run after installing/updating your package relative to the ``mainDirectory`` (optional).

Multiple such packages can be contained in one master configuration. It is also possible to create package groups like this:

<code json>
{
  "test-group-name": {
    "type": "group",
    "description": "Your group description goes here.",
    "packages": [
      "package1",
      "package2",
    ]
  }
}
</code>

And there are also virtual packages, which act the same as groups except you pick one package instead of installing all of them. They are made the same way as groups, just with ``type`` set to ``virtual-package``.

//Note that you may only use lowercase letters, numbers and dashes (``-``) in group names.//

  * ``test-group-name`` is your group's name;
  * ``type`` is the entry's type (in this case ``group``);
  * ``description`` is a brief description of your package group (optional);
  * ``packages`` is a list of packages in your group ([[avs|Advanced Versioning Syntax]] may be used here);

As you can see, package groups are much simpler. They aren't much but a way to install or uninstall many packages at once.

===== Versioning =====

It may occur that a certain package depends on a specific version of another package, and the latest version won't do. This is why all versions of a package should ideally be kept available at all times. This is done with some directories in your repository. For each package, there has to be a ``package-name-here-versions/`` directory in your repository's root. If this is not present, only the latest version of your package will be available, and packages that depend on older versions will break.

Inside the ``package-name-here-versions/`` directory, for each version there is another directory (for example, ``package-name-versions-versions/1.2.3``) which has all the files needed for the package and a copy of the master configuration (``ag2.json``) with only that package. There is also no mainDirectory option, as ``package-name-here-versions/1.2.3`` is set as the main directory and it would be pointless to change it.

Every time a new version is released, the corresponding directory in ``package-name-here-versions`` should be made and all the package's files and its config copied into it. If you use GitHub to host your repository, you can use this [[https://github.com/WahPlus/ArgentumPackages/tree/main/.github/workflows|nifty GitHub Action I've made]] to automate the process.