clyde 0.3.1

A cross-platform package manager for prebuilt applications
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

# 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][store-repo].

[store-repo]: https://github.com/agateau/clyde-store

Then we create a branch for your package.

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

```yaml
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:

- <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>

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:

```yaml
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:

```yaml
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:

```yaml
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](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.