clyde 0.4.0

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

# Package file format

This document describes the file format used by Clyde.

Clyde packages are defined as YAML files.

They can be either a directory: `<package_name>/index.yaml` or a plain file: `<package_name>.yaml`.

The directory format is supported since 0.4.0.

## Meta information

```yaml
name: foobar
description: Foo Bar Baz
# The public homepage
homepage: https://foobar.example.com
# Where the code can be downloaded. Optional.
repository: https://src.example.com
```

## Releases

Releases are stored in the `releases` mapping.

Each entry is a version, which itself contains entries for each arch-os asset.

Each asset as two entries: `url` and `sha256`.

```yaml
releases:
  "1.2.3":
    x86_64-linux:
      url: https://example.com/foobar/foobar-1.2.3-x86_64-linux.tar.gz
      sha256: 1234567890abcdef

    x86_64-macos:
      url: https://example.com/foobar/foobar-1.2.3-x86_64-macos.tar.gz
      sha256: 1234567890abcdef

    x86_64-windows
      url: https://example.com/foobar/foobar-1.2.3-x86_64-windows.zip
      sha256: 1234567890abcdef

    aarch64-macos:
      url: https://example.com/foobar/foobar-1.2.3-aarch64-macos.tar.gz
      sha256: 1234567890abcdef

  "1.2.1":
    x86_64-linux:
      url: https://example.com/foobar/foobar-1.2.1-x86_64-linux.tar.gz
      sha256: 1234567890abcdef
```

## Installs

Next is the "installs" entry. This entry tells Clyde how to install the downloaded asset.

`installs` is a mapping containing entries for the supported versions. There is not necessarily one entry for each version: the `clyde install` command uses the entry with the highest version which is lower than or equal to the version to install.

This means that if a package has `installs` entries for version 1.2.0 and 1.3.0, then installing 1.3.4 would use the 1.3.0 entries. Installing 1.2.4 would use the 1.2.0 entries.

Each version entry then contains arch-os entries. The arch and/or OS parts can be set to `any` if install instructions are independent of the arch and/or the OS.

Each arch-os entry can contain the following entries:

- `files`: a mapping of files contained in the asset to the place where they should be installed. See below for more examples.
- `strip` (optional): the number of directories to ignore inside the asset. For example if all files of foo-1.0.tar.gz are inside a `foo-1.0` directory, set `strip` to 1 to tell Clyde that all entries in `files` are *inside* this directory. Defaults to 0.
- `extra_files` (optional, since 0.4.0): the directory of a package using the directory format can contain an `extra_files` directory to provide files to install in addition to the asset files. This can be useful to provide launcher scripts, icons, or .desktop files. In this case this entry is a mapping of files from the `extra_files` directory to the place where they should be installed.
- `tests` (optional, since 0.4.0): a list of commands to run to verify the package is correct. Used by `clydetools check`.

Here is an example of an `installs` entry:

```yaml
installs:
  "1.2.0":
    any-any:
      # instructions for all arch-os

      # Ignore first level of directory. Defaults to 0 if not set.
      strip: 1

      files:
        # Copy "bin/foo" to "bin/foo":
        bin/foo: bin/foo

        # This can be simplified to:
        bin/foo: bin/
        # Note that for the destination to be interpreted as a directory, it
        # *must* end with a '/'.

        # Or even simpler:
        bin/foo:

        # But if the package has a Windows version, then the executable will be
        # called foo.exe, so for portability it's better to use the ${exe_ext}
        # variable. It expands to ".exe" on Windows and "" on other OSes.
        bin/foo${exe_ext}:

        # In this example, assuming "man" is a directory, its content is copied
        # recursively to "share/man"
        man: share/man

        # To install documentation, you can use the ${doc_dir} variable, which
        # expands to "share/doc/<package_name>/".
        # In this example "README.md" is copied to "share/doc/foobar/README.md".
        README.md: ${doc_dir}

      extra_files:
        # Copy "extra_files/bar" from within the package directory to "bin/bar"
        bar: bin/
    any-macos:
      # macOS special instructions
```

Packages must follow these rules:

- install binaries in `bin`
- install man pages in `share/man`
- install documentation in `share/doc/<package_name>` (use `${doc_dir}` for this, see "Variables" section)

If it is not possible to install the package files this way, then install all package files in `opt/<package_name>/`, add a launcher script to `extra_files` and install it in `bin`. Don't forget to make your launcher script executable.

### Variables

The source and destination parts of the `files` mapping support variables. A variable can be used with the `${variable_name}` syntax.

The following variables are available:

- `${asset_name}`: Name of the unpacked asset if the asset is a single-file asset. A single-file asset is an asset which is either the package executable, or a compressed version of it, compressed with gzip, bzip2 or xz. This variable is only available if the asset is a single-file asset.
- `${doc_dir}`: Directory storing the package documentation. Set to "share/doc/<package_name>/".
- `${exe_ext}`: Executable extension for the target OS. Set to ".exe" on Windows and "" on other OSes.

## Environment variables

Clyde activation scripts define a `$CLYDE_INST_DIR` environment variable pointing to Clyde prefix. This means Clyde `opt` directory for example, can be referred to as `$CLYDE_INST_DIR/opt`. Launcher scripts installed via `extra_files` can make use of the `$CLYDE_INST_DIR` environment variable to refer to a file installed in `$CLYDE_INST_DIR/opt/<package_name>`.