~cnx/ipwhl-docs

cd14486064e82f82aa642a3fabbc02b862d8a69c — Nguyễn Gia Phong 6 months ago a9594c7
Update guides to use ipwhl entry points
2 files changed, 12 insertions(+), 11 deletions(-)

M guides/contrib.md
M guides/use.md
M guides/contrib.md => guides/contrib.md +9 -6
@@ 83,11 83,14 @@ You can be the first one to add some!

### Updating metadata

First, install the `ipwhl` utilities, either directly from source
or using your package manager, and `cd data`.

The [mainline metadata Git repository][metadata] includes
the wheels declarations in `pkgs` and the supported platforms in `SUPPORTED`.
Inside `pkgs` each project is prefixed by the smallest 8 bits in lowercase
hexadecimal of the sum of its characters, which can be generated using
`utils/prefix.py $project`, where `$project` is the concerned project name.
`ipwhl-prefix $project`, where `$project` is the concerned project name.

Presuming you are trying to add the declaration for a wheel from `$project`
which is available on the [cheese shop], you can find the direct URL


@@ 102,7 105,7 @@ still preferable to urge the upstream maintainers to upload the wheels
to a platform with clear authority.

Once you have obtained the wheel URL, you can manually [declare according
to the specification][declare specs] or make use of `utils/declgen.py`.
to the specification][declare specs] or make use of `ipwhl-declgen`.
Either way, at first the wheel must be downloaded (let's say from `$url`)
and passed to `ipfs add --only-hash` for the CID, then the `METADATA` file
must be extracted to parse the requirements.  The script automates this


@@ 111,16 114,16 @@ the path to the newly generated declaration, which we shall refer to
as `$declaration`.

```sh
utils/declgen.py $url data/pkgs/$(utils/prefix.py $project)
ipwhl-declgen $url pkgs/$(ipwhl-prefix $project)
```

Floating cheeses declarations must satisfy [various requirements][checks],
which can be checked automatically:

```sh
utils/nameck.py data/pkgs
echo $declaration | utils/declck.py
utils/depsck.py data/pkgs < data/SUPPORTED
ipwhl-nameck pkgs
echo $declaration | ipwhl-declck
ipwhl-depsck pkgs < SUPPORTED
```

Common errors include a project's wheels being installable on a same platform

M guides/use.md => guides/use.md +3 -5
@@ 57,11 57,10 @@ to IPFS mutable file system (MFS):

    ipfs files cp /ipfs/<CID> /desired/mfs/path

Assuming one has the IPWHL [utilities Git repository] cloned at `utils`
and the derived declarations inside `data`, both in the same directory,
perse only need to run the following:
With the Python package `ipwhl` installed, one only need to run the following
inside the derived IPWHL declarations repository:

    utils/publish.py data/pkgs /desired/mfs/path
    ipwhl-publish pkgs /desired/mfs/path

If successful, the script will print to standard output the CID
of the newly published CID at the end of the execution.


@@ 71,4 70,3 @@ of the newly published CID at the end of the execution.
[announce mailing list]: https://lists.sr.ht/~cnx/ipwhl-announce
[metadata Git repository]: https://git.sr.ht/~cnx/ipwhl-data
[PEP 503]: https://www.python.org/dev/peps/pep-0503
[utilities Git repository]: https://git.sr.ht/~cnx/ipwhl-data