<commit_before>.. _package-management:

Package Management
==================

This document describes ``futhark pkg``, a minimalistic package
manager inspired by `vgo <https://research.swtch.com/vgo>`_.  A
Futhark package is a downloadable collection of ``.fut`` files and
little more.  There is a (not necessarily comprehensive) `list of
known packages <https://futhark-lang.org/pkgs>`_.

Basic Concepts
--------------

A package is uniquely identified with a *package path*, which is
similar to a URL, except without a protocol.  At the moment, package
paths are always links to Git repositories hosted on GitHub.  In the
future, this will become more flexible.  As an example, a package path
may be ``github.com/athas/fut-foo``.

Packages are versioned with `semantic version numbers
<https://semver.org/>`_ of the form ``X.Y.Z``.  Whenever versions are
indicated, all three digits must always be given (that is, ``1.0`` is
not a valid shorthand for ``1.0.0``).

Most ``futhark pkg`` operations involve reading and writing a *package
manifest*, which is always stored in a file called ``futhark.pkg``.
The ``futhark.pkg`` file is human-editable, but is in day-to-day use
mainly modified by ``futhark pkg`` automatically.

Using Packages
--------------

Required packages can be added by using ``futhark pkg add``, for example::

  $ futhark pkg add github.com/athas/fut-foo 0.1.0

This will create a new file ``futhark.pkg`` with the following contents:

.. code-block:: text

   require {
     github.com/athas/fut-foo 0.1.0 #d285563c25c5152b1ae80fc64de64ff2775fa733<commit_msg>GitLab also works.<commit_after>.. _package-management:

Package Management
==================

This document describes ``futhark pkg``, a minimalistic package
manager inspired by `vgo <https://research.swtch.com/vgo>`_.  A
Futhark package is a downloadable collection of ``.fut`` files and
little more.  There is a (not necessarily comprehensive) `list of
known packages <https://futhark-lang.org/pkgs>`_.

Basic Concepts
--------------

A package is uniquely identified with a *package path*, which is
similar to a URL, except without a protocol.  At the moment, package
paths are always links to Git repositories hosted on GitHub or GitLab.
In the future, this will become more flexible.  As an example, a
package path may be ``github.com/athas/fut-foo``.

Packages are versioned with `semantic version numbers
<https://semver.org/>`_ of the form ``X.Y.Z``.  Whenever versions are
indicated, all three digits must always be given (that is, ``1.0`` is
not a valid shorthand for ``1.0.0``).

Most ``futhark pkg`` operations involve reading and writing a *package
manifest*, which is always stored in a file called ``futhark.pkg``.
The ``futhark.pkg`` file is human-editable, but is in day-to-day use
mainly modified by ``futhark pkg`` automatically.

Using Packages
--------------

Required packages can be added by using ``futhark pkg add``, for example::

  $ futhark pkg add github.com/athas/fut-foo 0.1.0

This will create a new file ``futhark.pkg`` with the following contents:

.. code-block:: text

   require {
     github.com/athas/fut-foo 0.1.0 #d285563c25c5152b1ae80fc64de64ff2775fa733
{'fraction_non_alphanumeric': 0.12547169811320755, 'fraction_numerical': 0.023270440251572325, 'mean_word_length': 3.9625585023400935, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2855361', 'n_tokens_mistral': 1031, 'n_tokens_neox': 951, 'n_words': 399}