From f97216a60b4f77f6a75d69f5d4533773a1a28baa Mon Sep 17 00:00:00 2001 From: Alejandro R Mosteo Date: Tue, 1 Sep 2020 17:25:36 +0200 Subject: [PATCH] Documentation updates to reflect new manifests (#501) --- doc/catalog-format-spec.md | 198 +++++++++++++++++++------------------ doc/getting-started.md | 29 +++--- doc/publishing.md | 28 +++--- doc/user-changes.md | 26 +++++ 4 files changed, 151 insertions(+), 130 deletions(-) diff --git a/doc/catalog-format-spec.md b/doc/catalog-format-spec.md index 002d11c6..4fd0c250 100644 --- a/doc/catalog-format-spec.md +++ b/doc/catalog-format-spec.md @@ -2,28 +2,19 @@ ## Big picture -Each project is described as a TOML file. For instance: `aaa.toml` for the AAA -project, `gnatcoll.toml` for the package corresponding to GNATCOLL. +Each release belonging to a crate is described as a TOML file. This file has +minor differences depending on its location: a local manifest is found at the +top-level directory of the sources of a project, in which case its named +`alire.toml`, whereas a manifest found in an index (e.g., the community index), +is named `-.toml`. -Each TOML description contains an object that has a `general` table and then -one table per release. +Other than that, contents follow the same conventions and there are only slight +differences (some fields are intended only for an index manifest, and cannot +appear (or are optional) in a local manifest. These differences are pointed +out in the following descriptions, where necessary. -```toml -[general] -... - -['1.0'] -... - -['1.1'] -... - -['2.0'] -... -``` - -`general` contains information common to all releases, then each release -provides sources (`origin`) and can refine common information. +Each TOML description file contains exactly one release, but for the special +external definitions that are described in their own section. ## Information encoding @@ -61,8 +52,25 @@ environment is represented as a set of specific variables which can have a specific set of values: see the [Parameters](#parameters) section below for a comprehensive list. -To create atomic values in an environment-dependent way, use the following -construct (here to create a boolean): +All properties that support dynamic expressions follow the same structure, in +which the expression (case-like) is inserted between the key and its value. +Where a static expression would be + +```toml +key = "value" +``` + +one of its cases would be expressed by the following inline TOML table: + +```toml +key.'case(var)'.var_value = "value" +``` + +Several expressions can be inserted between a property key and its value, which +leads to combinatorial explosion if all cases have specific values. The +equivalent to an `others` Ada clause in this format is a `'...'` entry. + +Here is an example of a conditional boolean value. ```toml {'case(distribution)' = { @@ -78,7 +86,8 @@ construct (here to create a boolean): Depending on the value of the `distribution` environment variable, this will return `true` (its value is `debian` or `ubuntu`) or `false` (for other -values). +values). Note that these and following examples are not showing the +left-hand-side property to which such a value would be assigned. A little variation allows to build environment-dependent composite data. For instance, to make the dependency on `libbar` above dynamic: @@ -130,13 +139,16 @@ And finally for other `os` values: libfoo = "^1.2" ``` -## General Information +## Release Information -Unless specified, all the entries must be static, i.e. they cannot depend on -the context. +This section describes the actual properties that must or can appear in a +manifest file to describe a release. Unless specified, all the entries must be +static, i.e. they cannot depend on the context. -The `general` entry must contain an object. It contains itself the following -entries: + - `name`: mandatory string. The name of the crate this release belongs to. Use + `alr help identifiers` to see the rules such names must follow. + + - `version`: mandatory string. The semantic version of the release. - `description`: mandatory string. One-line description about the package. For instance: @@ -148,7 +160,7 @@ entries: - `long-description`: optional free-form string to provide information about this package, in addition to `description`, without length restrictions. -- `authors`: optional array of strings. Flat list of human-readable names for + - `authors`: optional array of strings. Flat list of human-readable names for the authors, i.e. the people that wrote the software that is packaged. For instance: @@ -157,25 +169,26 @@ entries: "Bob For Instance "] ``` - - `maintainers`: mandatory array of strings. Flat list of human-readable names - (optional) for the maintainers, with a contact email (mandatory); i.e. the - people that maintain the crate metadata in Alire. For instance: + - `maintainers`: mandatory (for indexing) array of strings. Flat list of + human-readable names (optional) for the maintainers, with a contact email + (mandatory); i.e. the people that maintain the crate metadata in Alire. For + instance: ```toml maintainers = ["alice@example.com", "Bob For Instance "] ``` - - `maintainers-logins`: mandatory array of strings. Flat list of github login - usernames used by the maintainers of the crate. This information is used to - authorize crate modifications. For instance: + - `maintainers-logins`: mandatory (for indexing) array of strings. Flat + list of github login usernames used by the maintainers of the crate. This + information is used to authorize crate modifications. For instance: ```toml maintainers-logins = ["alicehacks", "bobcoder"] ``` - - `licenses`: mandatory array of strings. Flat list of licenses for the - software that is packaged. The following licenses are allowed: + - `licenses`: mandatory (for indexing) array of strings. Flat list of licenses + for the software that is packaged. The following licenses are allowed: > - `AFL 3.0`, `AGPL 3.0`, `Apache 2.0`, `Artistic 2.0`, > `BSD 2-Clauses`, `BSD 3-Clauses Clear`, `BSD 3-Clauses`, @@ -223,8 +236,7 @@ entries: '...' = false ``` - - `depends-on`: optional dynamic dependencies expression common to all - releases. For instance: + - `depends-on`: optional dynamic dependencies expression. For instance: ```toml [depends-on] @@ -266,8 +278,8 @@ entries: TAG = "" ``` - - `gpr-set-externals`: optional table, giving a mapping from the name of - external variables to the values to use by default when building the + - `gpr-set-externals`: optional dynamic table, giving a mapping from the name + of external variables to the values to use by default when building the project. Expressions are accepted before the mapping. For instance: ```toml @@ -279,9 +291,9 @@ entries: windows = { OS = "ms-linux" } # to see all enumeration values, one per row. ``` - - `environment`: optional table used to modify environment variables that will - apply at build time. Variables and values are specified with the form - `VARIABLE. = "value"`, where `` is one of `append`, + - `environment`: optional dynamic table used to modify environment variables + that will apply at build time. Variables and values are specified with the + form `VARIABLE. = "value"`, where `` is one of `append`, `prepend`, or `set`. For instance: ```toml @@ -307,17 +319,17 @@ entries: msys2 = { C_INCLUDE_PATH.append = "${DISTRIB_ROOT}/mingw64/include/SDL2" } ``` - - `executables`: optional list of strings. Each one is the simple name of an - executable provided by the package. Executables are looked for by `alr` in - the build tree and must not include a path. If only one executable is given, - it is considered the default for `alr run`. For instance: + - `executables`: optional dynamic list of strings. Each one is the simple name + of an executable provided by the package. Executables are looked for by + `alr` in the build tree and must not include a path. If only one executable is + given, it is considered the default for `alr run`. For instance: ```toml executables = ["my_main"] ``` - - `actions`: optional list of actions to perform when installing this package. - The general action syntax is: + - `actions`: optional dynamic list of actions to perform when installing this + package. The general action syntax is: ```toml [[actions]] @@ -352,29 +364,45 @@ entries: # An explicit empty case alternative, which is not mandatory ``` - - `auto-gpr-with`: Boolean value that specifies if the project files of a - crate can be automatically 'withed' by the root project file (default is - true). This feature is meant to simplify the process of using dependencies - in Alire. However, not all project files are supposed to be withed, some can - be extended for instance, in that case a crate can disable the feature by - setting `auto-gpr-with=false`. + - `auto-gpr-with`: optional Boolean value that specifies if the project files + of a crate can be automatically 'withed' by the root project file (default + is true). This feature is meant to simplify the process of using dependencies + in Alire. However, not all project files are supposed to be withed, some can be + extended for instance, in that case a crate can disable the feature by setting + `auto-gpr-with=false`. -## Release-specific information + - `origin`: dynamic table. Mandatory for index manifests and forbidden in + workspace manifests. This table describes how sources are obtained, using + the following fields: -Each release is materialized as an entry in the top-level object. The key is a -string for the version number for the release, while the value is an object to -contain the release-specific information. This object can contains the -following entries: + - `url`: mandatory string which points to a source file or repository. - - `origin`: mandatory dynamic string expression. URL used to fetch the sources - to build. For instance: + - `hashes`: mandatory string array for source archives. An array + of "kind:digest" fields that specify a hash kind and its value. Kinds + accepted are: `sha512`. + + - `archive-name`: optional string. If `url` points to a source archive, + this can specify the name of the file to download, which is needed in + order to properly extract the sources, in case the URL does not identify it. + + - `commit`: mandatory string for VCS origins that describes the + VCS-specific revision to be checked out (a git/hg hash, a svn + revision). + + Examples of origin tables: ```toml # Clone a git repository - origin = "git+https://github.com/example-user/example-project" + [origin] + url = "git+https://github.com/example-user/example-project" + commit = "ec8b267bb8b777c6887059059924d823e9443439" + ``` + ```toml # Download and extract a source archive - origin = "https://example.org/archive.tar.gz" + origin = "https://example.org/0123456789" + archive-name = "archive.tar.gz" + hashes = ["sha512:bf6082573dc537836ea8506a2c9a75dc7837440c35c5b02a52add52e38293640d99e90a9706690591f8899b8b4935824b195f230b3aa1c4da10911e3caf954c04ac"] ``` If the package only maps a package from the system package manager, @@ -393,28 +421,8 @@ following entries: 'debian|ubuntu' = "native:make" ``` - - `origin-hashes`: mandatory string array for git origins and source archives. - An array of "kind:digest" fields that specify a hash kind and its value. - Kinds accepted are: `sha512`. - - - `archive-name`: optional string. If `origin` points to a source archive, - this can specifiy the name of the file to download, which is needed in order - to properly extract the sources. For instance: - - ```toml - origin = "https://example.org/0123456789" - archive-name = "archive.tar.gz" - archive-hash = "sha512:bf6082573dc537836ea8506a2c9a75dc7837440c35c5b02a52add52e38293640d99e90a9706690591f8899b8b4935824b195f230b3aa1c4da10911e3caf954c04ac" - ``` - - - `available`: optional dynamic boolean expression. It is used in the - following way: - - 1. If it evaluates to `false`, the package is not available for the current - platform. - - 1. Otherwise, the availability is determined by the `available` entry in the - `general` section. + - `available`: optional dynamic boolean expression. If it evaluates to + `false`, the package is not available for the current platform. - `notes`: optional string. Provides miscellanous information about this release. For instance: @@ -423,12 +431,6 @@ following entries: notes = "Experimental version" ``` -It can also contain the following entries: `depends-on`, `project-files`, -`gpr-externals`, `gpr-set-externals`, `executables`, `actions`. These are -optional. For atomic values, these override the ones from `general`, and for -lists/mappings, they are interpreted as additions. In the latter case, -conflicting entries are considered as errors. - ## External releases The above information applies to regular releases distributed from sources @@ -440,7 +442,7 @@ furthermore, its semantic version cannot be known until run time. Hence, the availability and version of these releases is detected by `alr`. Several definitions for these external releases may exist, and so they are -defined in the index as a vector with key `external`: +defined in a manifest as a vector with key `external`: ```toml [[external]] @@ -455,10 +457,10 @@ All external kinds can define these regular properties: - `available`: when defined, it restricts the external detection to the given environment conditions. - - `hint`: explanation for the user on how to make the external available. This - explanation is shown on request with `alr show --external`, or after - `alr get`, for any external dependency that could not be detected. This - property accepts dynamic expressions. + - `hint`: optional dynamic string containing an explanation for the user on + how to make the external available. This explanation is shown on request + with `alr show --external`, or after `alr get`, for any external dependency + that could not be detected. ### External kinds: hints diff --git a/doc/getting-started.md b/doc/getting-started.md index 3784b3af..8657a2ff 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -76,48 +76,45 @@ ease: ## Dependencies and upgrading -Alire keeps track of a project dependencies in the file -`./alire/project_name.toml` of your project. You may check the one just -created in the previous example. +Alire keeps track of a project dependencies in the file `./alire.toml` of your +project. You may check the one just created in the previous example. This file can be managed through `alr`: * `alr with project_name` adds a dependency. You can immediately 'with' its - GPR project files and packages in your code. + packages in your code. * `alr with --del project_name` removes a dependency. -* `alr with --from yourproject.gpr` reads the given GPR file and adds - dependencies specified in comments as alr invocations. For example: - ```Ada - with "xstrings"; -- alr with xstrings - project My_Project is - ``` +Using `alr with` without arguments will show the current dependencies of your +project. Using one of `--solve`, `--tree`, `--versions`, `--graph` will show +different details about the complete solution needed to fulfill dependencies. Alternatively you can edit the file (example in the works) to add dependencies and then issue: -* `alr update`, which will fetch any additional dependencies in your project. +* `alr update`, which will fetch any modified dependencies in your project. ## Finding available projects -For quick listing of projects and their descriptions you can use the `list` +For quick listing of crates and their descriptions you can use the `list` command: * `alr list [substring]` -There's also a `search` command which provides more details: +There's also a `search` command which provides more details about specific +releases: -* `alr search ` will look for `substring` in project names. +* `alr search ` will look for `substring` in crate names. * `alr search --list` will list the whole catalog. Even more details are obtained with: -* `alr show ` +* `alr show ` This last command will show generic information. To see the one that specifically applies to your platform: -* `alr show --system ` +* `alr show --system ` The list of projects and their descriptions are also available on the Alire website: diff --git a/doc/publishing.md b/doc/publishing.md index 690a48c0..c0e99d5c 100644 --- a/doc/publishing.md +++ b/doc/publishing.md @@ -12,9 +12,9 @@ The community index is a collection of [TOML](https://github.com/toml-lang/toml) files stored in the [alire-index](https://github.com/alire-project/alire-index) repository, under the [index](https://github.com/alire-project/alire-index/blob/master/index) -directory. Each file is named after the crate it contains. A crate contains the -description of a project, with other metadata, and the list of available -releases (identified by their [semantic version](https://semver.org/)). +directory. Each file contains a release for a crate and is named after the +crate and version it contains. A crate contains the description of a release, +with other metadata. The complete specification of such TOML files is available in this [document](catalog-format-spec.md). @@ -22,9 +22,7 @@ The complete specification of such TOML files is available in this ## New crates and releases Publishing a new crate is achieved through a pull-request against the index -repository, in which the TOML file for the crate must be provided. Similarly, a -new release is published by submitting a pull-request with the necessary -modifications to the crate file. +repository, in which the TOML file for the release must be provided. ### Index branches @@ -55,9 +53,7 @@ or metadata modifications to the corresponding crate file. ## Detailed steps -These steps describe how to submit a new crate. They are essentially the same -for submitting a new release (in the latter case, the existing crate file must -be edited instead of created). +These steps describe how to submit a new release. 1. Prepare a source archive (zip, tar) with the release sources and project files. @@ -78,14 +74,14 @@ be edited instead of created). conversation](https://github.community/t5/How-to-use-Git-and-GitHub/Ensuring-identical-tarballs-from-releases/m-p/34196/highlight/true#M8997)). In the future, `alr publish` will offer support to generate and upload such files more conveniently. -1. Fill the crate file providing all the necessary information (`[general]` - section), dependencies (`depends-on`) and possibly excluded platforms +1. Fill in the release manifest providing all the necessary information, + dependencies (`depends-on`) and possibly excluded platforms (`available`). See, for example, the [hello - world](https://github.com/alire-project/alire-index/blob/master/index/he/hello.toml) + world](https://github.com/alire-project/alire-index/blob/master/index/he/hello/hello-1.0.1.toml) crate, or the [empty skeleton](https://github.com/alire-project/alire-index/blob/master/templates/skeleton.toml) template. -1. Place the crate file in the appropriate directory of your locally checked +1. Place the manifest file in the appropriate directory of your locally checked out index repository, and create a new pull request. The detailed substeps are the usual for submitting contributions in GitHub: 1. Fork the community index to your GitHub account. @@ -98,6 +94,6 @@ be edited instead of created). your changes will become available; see the section on [index branches](#index-branches) for details. -Once the pull request is verified and merged, the new crate or release will -become available for normal use. The open source Ada ecosystem needs all the -help it can get, so happy contributing! +Once the pull request is verified and merged, the new release will become +available for normal use. The open source Ada ecosystem needs all the help it +can get, so happy contributing! diff --git a/doc/user-changes.md b/doc/user-changes.md index e76ee41f..3e3c7045 100644 --- a/doc/user-changes.md +++ b/doc/user-changes.md @@ -6,6 +6,32 @@ stay on top of `alr` new features. ### New `alr with --versions` switch +PR [#501](https://github.com/alire-project/alire/pull/501). + +The metadata information about a crate/release has been reworked to simplify +user workflows and internal operation. Metadata is stored in the manifest file, +which as of this PR is always called `alire.toml` and located at the root +directory of an Alire-enabled workspace. A companion lock file, `alire.lock`, +stores information about the dependency solution and overrides. + +These two files can be safely put under version control. The manifest, in +particular, is intended to evolve with your Ada project, by being an up-to-date +record of any necessary dependencies and other properties (version, project +files, executables, maintainers, etc.). + +The manifest internal format has been simplified by eliminating the possibility +of multiple releases from its contents, which removes some nesting, and +removing or making optional some fields that only make sense at the time of +publishing a crate to some index. Check the [catalog-format-spec.md] file for +details. + +The `alire` directory continues to exist, and it is used to store the source +code of dependencies, local configuration and backup files. It can be safely +ignored for VCS, as its contents are either not critical or can be +reconstructed from the manifest information. + +### New `alr with --versions` switch + PR [#464](https://github.com/alire-project/alire/pull/464). A new `alr with --versions` switch is available to obtain version-focused -- 2.39.5