Skip to content

Commit

Permalink
Add registry documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@kubouch
kubouch committed Mar 28, 2024
1 parent 66b9cb2 commit bde509c
Show file tree
Hide file tree
Showing 2 changed files with 97 additions and 23 deletions.
116 changes: 95 additions & 21 deletions docs/design/registry.md
View file
Original file line number Diff line number Diff line change
@@ -1,29 +1,103 @@
# Registry

_moved from old registry.nuon_
Registry is a collection of .nuon files that tell nupm where to look for packages when doing tasks like `nupm search` or `nupm install`.

Registry is a NUON file that tells nupm where to look for packages
Two types of files compose a registry:
* The "main" registry file containing the list of "registry package files"
* Registry package files containing the details of each package.

Currently, these package types are supported:
* git ..... package is an online git repository
* local ... package is on a local filesystem
These files **should not** be edited manually. They are intended to be auto-generated and updated with `nupm publish` only.

The package type defines the columns of the registry record. Each column holds
holds a table of packages.
## "Main" registry file

Git packages accept the following columns:
* name ....... name of the package
* version .... version of the package
* url ........ Git URL of the package
* revision ... Git revision to check out when installing the package (commit
hash, version, branch name, ...)
* path ....... Path relative to the repository root where to look for nupm.nuon
Table with one package per row and the following columns:
* `name`: Name of the package
* `path`: Path to the "registry package file", relative* to the main registry file. When looking up a package, nupm joins this path to the path/URL of the "main" registry file and fetches it. Both local paths and URLs are handled the same way.
* `hash`: Hash of the "registry package file" to avoid re-downloading them all the time.

Local packages accept the following columns:
* name ....... name of the package
* version .... version of the package
* path ....... Path where to look for nupm.nuon. It can be absolute, or
relative. If relative, then relative to the registry file.
The file is sorted by `name`. No duplicate package names allowed.

One registry can contain packages with the same name, but they must be of
different version.
## "Registry package file"

These files contain the actual information about the package that is used do fetch and install the package. Multiple versions of the same package are supported. It has exactly the following columns:
* `name`: Name of the package
* `version`: Version of the package
* `path`: Path where to look for nupm.nuon (relative to the package root*)
* `type`: Type of the package. Currently only "git" and "local"
* `info`: Package-specific info based on `type`. It can be one of the following:
* `null` if `type` is "local"
* `record<url: string, revision: string>` if `type` is "git"

This file is sorted by `version`. No duplicate versions allowed.

_*absolute paths work, but are discouraged, only to be used for local testing etc._

## Example registry structure

_See the new `registry/` directory, the following example slightly differs from it._

```
./registry
+-- registry.nuon
+-- amtoine
+-- nu-git-manager.nuon
+-- nu-git-manager-sugar.nuon
```

```nushell
> open registry/registry.nuon
# name path hash
───────────────────────────────────────────────────────────────────────────
0 nu-git-manager amtoine/nu-git-manager.nuon md5-4aaae15412fb84233fcb19716f6b7e89
1 nu-git-manager-sugar amtoine/nu-git-manager-sugar.nuon md5-d0c7641c0b369e7c944cc668741734d9
> open amtoine/nu-git-manager.nuon | table -e
# name version path type info
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
0 nu-git-manager 0.1.0 pkgs/nu-git-manager git url https://github.com/amtoine/nu-git-manager
revision 0.1.0
1 nu-git-manager 0.2.0 pkgs/nu-git-manager git url https://github.com/amtoine/nu-git-manager
revision 0.2.0
2 nu-git-manager 0.3.0 pkgs/nu-git-manager git url https://github.com/amtoine/nu-git-manager
revision 0.3.0
3 nu-git-manager 0.4.0 pkgs/nu-git-manager git url https://github.com/amtoine/nu-git-manager
revision 0.4.0
4 nu-git-manager 0.5.0 pkgs/nu-git-manager git url https://github.com/amtoine/nu-git-manager
revision 0.5.0
5 nu-git-manager 0.6.0 pkgs/nu-git-manager git url https://github.com/amtoine/nu-git-manager
revision 0.6.0
6 nu-git-manager 0.7.0 pkgs/nu-git-manager git url https://github.com/amtoine/nu-git-manager
revision 0.7.0
> open amtoine/nu-git-manager-sugar.nuon | table -e
# name version path type info
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
0 nu-git-manager-sugar 0.1.0 pkgs/nu-git-manager-sugar git url https://github.com/amtoine/nu-git-manager
revision 0.1.0
1 nu-git-manager-sugar 0.2.0 pkgs/nu-git-manager-sugar git url https://github.com/amtoine/nu-git-manager
revision 0.2.0
2 nu-git-manager-sugar 0.3.0 pkgs/nu-git-manager-sugar git url https://github.com/amtoine/nu-git-manager
revision 0.3.0
3 nu-git-manager-sugar 0.4.0 pkgs/nu-git-manager-sugar git url https://github.com/amtoine/nu-git-manager
revision 0.4.0
4 nu-git-manager-sugar 0.5.0 pkgs/nu-git-manager-sugar git url https://github.com/amtoine/nu-git-manager
revision 0.5.0
5 nu-git-manager-sugar 0.6.0 pkgs/nu-git-manager-sugar git url https://github.com/amtoine/nu-git-manager
revision 0.6.0
6 nu-git-manager-sugar 0.7.0 pkgs/nu-git-manager-sugar git url https://github.com/amtoine/nu-git-manager
revision 0.7.0
```

## Publishing a package

It is possible to only publish to a registry stored on your file system because we don't have a web service or anything like that.

The intented workflow for publishing a package is:
1. Check out the git repository with the registry
2. `cd` into the package you want to publish
3. Run `nupm publish chosen_registry` to preview the changes
4. Repeat 3 by adjusting the `nupm publish` flags until you have the desired output
5. Run the final command with the `--save` flag which will save the registry files
6. Commit the changes to the registry, create a PR upstream, etc.

The reason for steps 3. and 4. is that `nupm publish` tries to guess some values to make publishing less tedious. For example, if you're in a git repository, nupm tries to get the URL of the "origin", or the first available remote by default. This should be a sane default for most packages and frees you from having to pass the `--info` flag every time. The guess can be wrong, however, that's why you should check the output of step 3 and make the desired changes before saving the changes with `--save`.
4 changes: 2 additions & 2 deletions nupm/publish.nu
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@ use utils/version.nu sort-by-version
# By default, changes are only previewed. To apply them, use the --save flag.
# Needs to run from package root, i.e., where nupm.nuon is.
export def main [
registry: string # Registry file to publish to (name or path)
registry: string # Registry file to publish to (local file or name pointing
# at a local registry)
--git # Publish package as a git package
--local # Publish package as a local package
--info: record # Package info based on package type (e.g., url and
# revision for a git package)
--path: string # Path to the package root relative to the registry file
# --pkg-file-url: string # URL of a package registry file
--save # Write changes to registry instead of printing changes
] {
if $git and $local {
Expand Down

0 comments on commit bde509c

Please sign in to comment.