Skip to content

Latest commit

 

History

History
136 lines (98 loc) · 4.95 KB

creating-a-package.md

File metadata and controls

136 lines (98 loc) · 4.95 KB

Creating a package

Introduction

This document explains how to create a package for an imaginary application called namcap.

Setup

We start by cloning the Clyde store repository.

Then we create a branch for your package.

Then we create a file named namcap.yaml in the repository, with the following content:

name: namcap
description: A one line description of the namcap app
homepage: https://namcap.example.com

Adding release assets

Now we need to add release assets. Clyde provides a tool to help with this: clydetools add-assets.

Let's say namcap provides the following archives for version 1.2.3:

To use all these archives for the 1.2.3 release, run clydetools add-assets like this:

clydetools add-assets namcap.yaml 1.2.3 \
    https://namcap.example.com/download/namcap-1.2.3-x86_64-linux.tar.gz \
    https://namcap.example.com/download/namcap-1.2.3-x86_64-windows.zip \
    https://namcap.example.com/download/namcap-1.2.3-x86_64-darwin.tar.gz \
    https://namcap.example.com/download/namcap-1.2.3-aarch64-darwin.tar.gz

clydetools add-assets downloads all archives, computes their sha256 checksum, and adds them as builds for the 1.2.3 release to namcap.yaml.

Our namcap.yaml should now look like this:

name: namcap
description: A one line description of the namcap app
homepage: https://namcap.example.com
releases:
  1.2.3:
    aarch64-macos:
      url: https://namcap.example.com/download/namcap-1.2.3-aarch64-darwin.tar.gz
      sha256: some_sha256_checksum
    x86_64-linux:
      url: https://namcap.example.com/download/namcap-1.2.3-x86_64-linux.tar.gz
      sha256: some_sha256_checksum
    x86_64-macos:
      url: https://namcap.example.com/download/namcap-1.2.3-x86_64-macos.tar.gz
      sha256: some_sha256_checksum
    x86_64-windows
      url: https://namcap.example.com/download/namcap-1.2.3-x86_64-windows.zip
      sha256: some_sha256_checksum

Adding installs

It's time to add an installs entry so that Clyde knows which files should go where.

Let's assume the archive content is the following:

namcap-1.2.3-$arch-$os/
  namcap (namcap.exe on Windows)
  README.md
  LICENSE
  doc/
    GUIDE.md
    namcap.1

This is what the installation must do:

  • namcap (namcap.exe on Windows) must go to the bin directory
  • namcap.1 must go to the share/man/man1 directory
  • The other files must go to the package documentation directory (share/doc/namcap)

We can do this with an installs entry like this:

installs:
  1.2.3:
    any-any:
      strip: 1
      files:
        namcap${exe_ext}: bin/
        doc/namcap.1: share/man/man1/
        README.md: ${doc_dir}
        LICENSE: ${doc_dir}
        doc/GUIDE.md: ${doc_dir}

Let's unpack this. We start with the version number: it says Clyde that version 1.2.3 or later of the namcap package must follow these instructions (This means if we later add a new version of the application but whose archive content is organized the same way, we don't need to add another entry to the installs entry).

Then there is an any-any entry: the first any is for the architecture (x86_64, aarch64...). Since we do not have architecture-specific rules, we use any. The second any is for the OS (linux, macos, windows). Again since we do not have OS-specific rules, we use any.

Then strip: 1 tells Clyde to skip the first subdirectory of the archive (the namcap-1.2.3-$arch-$os part).

Finally, the files part defines where each file go. There are a few subtleties here:

  • For the executable we use the ${exe_ext} variable to transparently handle the fact that Windows binaries have a ".exe" extension.
  • To install to a directory, it must end with a /, writing doc/namcap.1: share/man/man1 would mean moving namcap.1 to share/man and renaming it to man1.
  • To install to the documentation directory, we can use the ${doc_dir} variable.

For more details on the file format, have a look at the package-file-format.md document.

Testing it

We are done, time to test the package. Run clyde install namcap.yaml and see if it works as expected.

If you don't want to "pollute" your installation, you can setup a separate Clyde home by defining the CLYDE_HOME environment variable:

export CLYDE_HOME=/tmp/my-test-home
clyde setup
. $CLYDE_HOME/scripts/activate.sh
clyde install namcap.yaml

If some files are not at the right place, uninstall the package with clyde uninstall namcap (not namcap.yaml!) and reinstall.

Sharing it

Congratulations! Our package is ready, you can now commit your new file and open a pull request to add your package to the store.