|
|
@@ -15,7 +15,7 @@ The USM manifest file is contains a JSON object with the following properties:
|
|
|
- `"1.1.2"` for a regular release.
|
|
|
- `"1.1.2+1` for the same version, but with a fix to the packaging.
|
|
|
- `summary` (string, required): A short summary describing the package, e.g. `Universal Source Manifest` for the package `usm`.
|
|
|
-- `liceences` (array, required): A list of licences applicable to this package, the array contains a license object with thr following required properties:
|
|
|
+- `licences` (array, required): A list of licences applicable to this package, the array contains a license object with thr following required properties:
|
|
|
- `name` (string, required): The name of the licence.
|
|
|
- `text` (string, required): The path, relative to the MANIFEST.usm of the full text of the licence.
|
|
|
- `category` (string, required): Must be one of:
|
|
|
@@ -37,7 +37,7 @@ The USM manifest file is contains a JSON object with the following properties:
|
|
|
- The value may be either:
|
|
|
- An object with the following properties:
|
|
|
- `path` (string): The path to the resource file, relative to `pathBase`. Required when `type` is `"reg"` and `pathBase` is not `"as-expected"`, must not be set otherwise.
|
|
|
- - `pathBase` (string): What the `path` property is relative to. It is required when `type` is `"reg"` and must not be set otherwise. It can be set to one of the following:
|
|
|
+ - `pathBase` (string): What the `path` property is relative to (see [Installation Lifecycle Directories](#installation-lifecycle-directories)). It is required when `type` is `"reg"` and must not be set otherwise. It can be set to one of the following:
|
|
|
- `"source"`: referencing the path to the extracted source code.
|
|
|
- `"build"`: referencing the path to the built output (e.g. where the result of `make` might go).
|
|
|
- `"install"`: referencing the path to the install output (e.g. where the result of `make install` might go).
|
|
|
@@ -65,8 +65,74 @@ The USM manifest file is contains a JSON object with the following properties:
|
|
|
- `flags` (string array, required): A list of flags for this manifest, each string in the array can be one of the following:
|
|
|
- `"buildInSourceTree"` to tell usm to not create a separate build directory, and compile the package "in place".
|
|
|
- `"setManifestPropertyEnvs"` idk TODO
|
|
|
+- `execs` (object, required): An object describing executable scripts for different phases of the package lifecycle (see [Executable Scripts](#executable-scripts)). It has the following properties :
|
|
|
+ - `build` (string, required): Path to the build script relative to the package root.
|
|
|
+ - `install` (string, optional): Path to the install script relative to the package root.
|
|
|
+ - `remove` (string, optional): Path to the removal script relative to the package root.
|
|
|
+ - `postInstall` (string, optional): Path to the post-install script relative to the package root.
|
|
|
+ - `acquire` (string, optional): Path to the acquire script relative to the package root.
|
|
|
+- `md` (string, optional): Path to a markdown file containing a detailed description of the package, relative to the package root.
|
|
|
+- `url` (string, optional): URL to the project's website or repository.
|
|
|
+- `screenshots` (string array, optional): Array of paths to screenshot files, relative to the package root.
|
|
|
+- `icon` (string, optional): Path to an icon file for the package, relative to the package root.
|
|
|
+- `metainfo` (string, optional): Path to a metainfo file following the AppStream specification, relative to the package root.
|
|
|
+- `git` (object, optional): Git repository information with the following properties:
|
|
|
+ - `origin` (string, required): URL to the git repository.
|
|
|
+ - `commit` (string, required): Specific commit hash, tag, or branch to use.
|
|
|
+- `extras` (object, optional): Additional properties that don't fit into the standard schema.
|
|
|
|
|
|
+## Resource References
|
|
|
|
|
|
-
|
|
|
+Resource references are strings in the format `[resource-type]:[resource-name]` that identify specific resources provided or required by a package. The resource type determines where the resource is located or expected to be found on the filesystem.
|
|
|
|
|
|
-## Resource References
|
|
|
+### Resource Types
|
|
|
+
|
|
|
+The following resource types are defined:
|
|
|
+
|
|
|
+- `rootpath`: A resource located at the root of the filesystem (`/[resource-name]`).
|
|
|
+- `path`: A resource located in the `/usr` hierarchy (`/usr/[resource-name]`).
|
|
|
+- `opt`: A resource located in the `/opt` hierarchy (`/opt/[resource-name]`).
|
|
|
+- `res`: A resource located in the `/usr/share` hierarchy (`/usr/share/[resource-name]`).
|
|
|
+- `cfg`: A resource located in the `/etc` hierarchy (`/etc/[resource-name]`).
|
|
|
+- `bin`: An executable binary located in the system PATH.
|
|
|
+- `sbin`: A system executable binary located in `/usr/sbin` or `/sbin`.
|
|
|
+- `lib`: A shared library located in the system library paths.
|
|
|
+- `libexec`: A library executable located in `/usr/libexec`.
|
|
|
+- `libres`: A library resource located in `/usr/lib`, `/usr/lib64`, `/lib`, or `/lib64`.
|
|
|
+- `info`: An info page located in `/usr/share/info`.
|
|
|
+- `man`: A manual page located in `/usr/share/man`.
|
|
|
+- `locale`: A locale resource located in `/usr/share/locale`.
|
|
|
+- `app`: An application desktop file located in `/usr/share/applications`.
|
|
|
+- `inc`: A C/C++ header file located in `/usr/include`.
|
|
|
+- `pc`: A pkg-config file located in the system pkg-config paths.
|
|
|
+- `vapi`: A Vala API file located in `/usr/share/vala/vapi` or `/usr/share/vala-0.56/vapi`.
|
|
|
+- `gir`: A GObject Introspection file located in `/usr/share/gir`.
|
|
|
+- `typelib`: A GObject typelib file located in `/usr/lib64/girepository-1.0`, `/usr/lib/girepository-1.0`, `/lib64/girepository-1.0`, or `/lib/girepository-1.0`.
|
|
|
+- `tag`: A tag resource managed by the USM system.
|
|
|
+
|
|
|
+### Example Resource References
|
|
|
+
|
|
|
+- `bin:ls`: The `ls` executable binary.
|
|
|
+- `lib:libc.so.6`: The libc shared library.
|
|
|
+- `man:ls.1`: The manual page for the `ls` command.
|
|
|
+- `cfg:myapp.conf`: A configuration file for `myapp`.
|
|
|
+- `app:myapp.desktop`: A desktop entry for `myapp`.
|
|
|
+
|
|
|
+## Installation Lifecycle Directories
|
|
|
+
|
|
|
+Each of these directories are created by USM at runtime for each package.
|
|
|
+
|
|
|
+- The source directory (`"pathBase": "source"`) is where the source code is extracted to (in the case of a `.usmc` package), or acquired into (when using an `acquire` exec).
|
|
|
+- The build directory (`"pathBase": "build"`) is where the `build` exec is instructed to output the built program to.
|
|
|
+- The install directory (`"pathBase": "install"`) is where the `install` exec (if applicable) is instructed to install the program to (i.e. the `DESTDIR` in most build systems).
|
|
|
+
|
|
|
+
|
|
|
+## Executable Scripts
|
|
|
+
|
|
|
+All executable scripts except for `remove` and `postInstall` are run from the source directory (see above). They may be anywhere in the source package, but are often placed in a folder at the root of the package called `scripts`.
|
|
|
+
|
|
|
+- `build` is the only required exec script, it has the needed commands to actually compile the program from source. The build directory is passed to this exec as the first argument.
|
|
|
+- `install` when specified will install the files into the install directory, in the same structure that it would if that directory were the filesystem root. The build directory is passed to this exec as the first argument, the install directory is passed as the second argument, and the install type ("fresh", "upgrade", "downgrade") is passed as the third argument.
|
|
|
+- `remove` is called just before USM deletes the resources of a package on uninstallation. The remove type ("final", "upgrade", "downgrade") is passed as the first argument.
|
|
|
+- `postInstall` is called after USM has installed the packages resources to the system. The build directory is passed to this exec as the first argument, and the install type ("fresh", "upgrade", "downgrade") is passed as the second argument.
|
|
|
+- `acquire` is used to download the authoritative sources. It is usually used by package maintainers when a project does not natively have `MANIFEST.usm` support to enable putting many USM manifests into a repository, and using tooling to download and extract the sources to make `.usmc` (USM Complete) packages. This script usually consists of either a `git clone` command, or a `wget` call followed by an archive extraction command. No parameters are passed to this exec.
|
