chore: update documentation for indexers

This commit is contained in:
DavHau 2022-08-31 20:59:19 +02:00
parent dc3530785e
commit a015a05db4

View File

@ -2,30 +2,36 @@
Indexers are programs that can query a package repository (think of npm, or crates.io) for package information. Indexers are programs that can query a package repository (think of npm, or crates.io) for package information.
This information mainly consists of the package name, the package version, and anything extra that might be useful / needed to fetch / translate it. This information mainly consists of the package name, the package version, and anything extra that might be useful / needed to fetch / translate it.
The information is stored as a "source shortcut", which basically follows the format `proto1+proto2:pname/version?key=value&key2=value2`. The information is stored as JSON (see below).
Examples:
- `npm:execa/6.1.0`
- `crates-io:ripgrep/13.0.0?hash=somehash`
- `git+ssh://github.com/owner/repo?rev=refs/heads/v1.2.3&dir=sub/dir`.
- etc.
## Indexer inputs ## Indexer inputs
Indexers take input as a path to a JSON file, which contains information needed by that specific indexer. Indexers take input as a path to a JSON file, which contains custom arguments for the indexer.
A common attribute for these inputs across indexers are `outputFile`, which should be the path to output the generated index to. A common attribute for these inputs across indexers are `outputFile`, which should be the path to output the generated index to.
Indexers can vary in functionality, so these JSON inputs should be specified under `src/specifications/indexers/`. Indexers can vary in functionality, so these JSON inputs should be specified under `src/specifications/indexers/`.
## Indexer outputs ## Indexer outputs
Indexers should output their generated index to where `outputFile` specifies. Indexers should output their generated index to where `outputFile` specifies.
This index should simply be a list of source shortcuts in JSON. Example: This index should simply be a list of project specifications in JSON. Example:
```json ```json
[ [
"npm:execa/6.1.0", {
"npm:meow/10.1.3", "name": "execa",
"npm:npm-run/5.0.1" "version": "6.1.0",
"translator": ["npm"]
},
{
"name": "meow",
"version": "10.1.3",
"translator": ["npm"]
},
{
"name": "npm-run",
"version": "5.0.1",
"translator": ["npm"]
}
] ]
``` ```
@ -33,5 +39,7 @@ This index should simply be a list of source shortcuts in JSON. Example:
Following are the current indexers implemented in dream2nix: Following are the current indexers implemented in dream2nix:
- crates.io indexer (named `crates-io`) - **crates-io-simple**: crates.io indexer
- NPM indexer (named `npm`) - **crates-io**: crates.io indexer written in rust with more options
- **libraries-io**: multi ecosystem indexer utilizing libraries.io (requires API key)
- **npm**: simple indexer using npm's registry