Home Explore Help
Sign In
Tilo15
/
usm
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: 7dedf6b6e4
Branches Tags
usm
/
SPECIFICATION.md

SPECIFICATION.md 14 KB
History Raw

USM Manifest JSON Schema Specification

Overview

The USM (Universal Source Manifest) is a JSON-based format that defines the structure and metadata of a software package. It provides all necessary information for building, installing, and managing software packages across different systems.

The manifest file must be named named MANIFEST.usm and is located at the root of a software project.

Schema Structure

The USM manifest file is contains a JSON object with the following properties:

  • name (string, required): The name of the software package (no spaces allowed).
  • version (string, required): The semantic version of the package, with an optional package version separated by a +, e.g.:
    • "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.
  • 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:
      • "libre": for software that meets the four essential freedoms, that being (from gnu.org):
        • The freedom to run the program as you wish, for any purpose (freedom 0).
        • The freedom to study how the program works, and change it so it does your computing as you wish (freedom 1). Access to the source code is a precondition for this.
        • The freedom to redistribute copies so you can help others (freedom 2).
        • The freedom to distribute copies of your modified versions to others (freedom 3). By doing this you can give the whole community a chance to benefit from your changes. Access to the source code is a precondition for this.
      • "open-source": for software which may be regarded as "open source" but fall short of the free software definition. In cases where an "open-source" licence does meet all the criteria to be considered free/libre software (by the above definition), "libre" must be used instead. Examples of licences considered open-source but not libre include:
        • The NASA Open Source Agreement v1.3 is not recognised as a "libre" licence because it includes a provision requiring changes to be your “original creation”, conflicting with "freedom 1" since you cannot make changes that incorporate intellectual property that may be under a permissive licence.
        • The Artistic-1.0 licence is too vague and might not protect the user's freedoms.
      • "source-available": for software that makes the full source code available, but has restrictions on what the user can do with the software, or the source code. Examples include:
      • "proprietary": for everything else.
  • provides (object, required): An dictionary object containting properties describing the resources that this software package provides:
    • The property name must be a ResourceRef string describing a resource that this package provides.
    • 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 (see 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).
          • "as-expected" which will copy the file from the install output (e.g. where the result of make install might go) in the place expected for a resource of the type and name specified by the ResourceRef. When in use, path must be an empty string.
        • type (string, required): The type of filesystem entry for this resource, can be one of the following:
          • "reg": For regular files.
          • "dir": For making directories.
          • "lnk": For symbolic links.
        • dest (string): The destination for the symbolic link. Required when type is "lnk" and must not be set otherwise.
        • keepOn (string array): For setting restrictions on deleting this resource, each string in the array can be one of the following:
          • "final": To inhibit deletion when the package is being uninstalled at the request of the user.
          • "upgrade": To inhibit deletion of the resource when the package is being uninstalled to make way for an updated version.
          • "downgrade": To inhibit deletion of the resource when the package is being uninstalled to make way for an older version.
        • skipFor (sting array): For setting restrictions on installing this resource, each string in the array can be one of the following:
          • "fresh": To inhibit installation of the resource when the package is being installed for the first time.
          • "upgrade": To inhibit the installation of the resource when the package is being updated to a newer version.
          • "downgrade": To inhibit the installation of the resource when the package is being downgraded to an older version.
      • A shorthand string in the format [path-base]:[path] describing the file path to the resource so that it can be copied on installation (see pathBase and path properties above).
      • The literal string "as-expected" (sans colon) which has the same meaning as {"pathBase": "as-expected"} above.
  • depends (object, required): An object with the following properties describing different kinds of package dependencies:
    • runtime (string array, required): Each string must be a ResourceRef describing the resources this package needs at runtime.
    • build (string array, required): Each string must be a ResourceRef describing the resources this package needs at compile (build) time.
    • manage (string arraym required): Each string must be a ResourceRef describing the resources needed to run the processes specified in the execs section of the manifest (other than acquire).
    • acquire (string array): Each string must be a ResourceRef describing the resources this package needs to run the acquire script (when specified on the acquire property of the execs object).
  • 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). 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 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.