FoBiS.py

Appearance

1. An index of your own ​

This track follows a lab that writes Fortran libraries and wants its people, and anyone else, to use them by name. There is no package server to set up: each library is a git repository whose tags are its versions, and an index is a small file listing where the libraries are. Chapter 8 of the second track showed the idea on one project; this track goes through every part of it.

The lab has three libraries, each a git repository with a version tag: kinds (real kinds), vectors (small vectors, using kinds) and timer. A vendor publishes another library also called kinds. In the sessions they live in ~/remotes, published by a small script; on a real host they would be URLs like https://git.example.org/lab/kinds.

Seeds, then an index ​

The lab lists only where its libraries are, in a seed file. kinds gets keywords written by hand:

console
$ cat ~/lab-index/seeds.toml
# the lab's packages: a source each; index build reads the rest from the sources
schema = 1
name   = "lab"
description = "The packages of our lab"

[package.kinds]
source   = "file://~/remotes/kinds.git"
keywords = ["kinds", "precision"]

[package.vectors]
source = "file://~/remotes/vectors.git"

fobis index build reads each source and fills the rest:

console
$ cd ~/lab-index && fobis index build seeds.toml -o index.toml
Wrote index.toml: 2 package(s)
console
$ cat ~/lab-index/index.toml
schema = 1
name = "lab"
description = "The packages of our lab"

[package.kinds]
source = "file://~/remotes/kinds.git"
description = "Portable real kinds"
license = "MIT"
keywords = ["kinds", "precision"]
provides = ["kinds"]
builds = ["fobis"]

[package.vectors]
source = "file://~/remotes/vectors.git"
description = "Small vectors of reals"
license = "MIT"
provides = ["vectors"]
builds = ["fobis"]

Descriptions and licences come from each library's fobos [project], provides lists the modules of its newest version, and builds its build systems. No version is written: the versions are the repositories' tags, read when the libraries are used, so tagging a release is publishing it. Fields written by hand in the seeds (the keywords) win when the index is built again.

Check it ​

fobis index check validates an index, and --online also reads every source:

console
$ fobis index check ~/lab-index/index.toml --online
~/lab-index/index.toml: valid index 'lab', 2 package(s)

It refuses a key it does not know, so a typo is caught where the index is written:

console
$ fobis index check ~/typo.toml
Error: index ~/typo.toml: [package.kinds]: unknown key(s) keyword
[exit status 2]

The commands that only read an index (search, info, add) ignore keys they do not know, with a note: a key added by a newer FoBiS never breaks an older one.

Use the index, and another one ​

An index is registered by name. A directory, a git repository or a static index.toml on a web server all work:

console
$ fobis index add lab ~/lab-index
lab: 2 package(s), dir index
Added index lab = ~/lab-index to ~/.config/fobis/config.ini

The vendor's index lists its own kinds, and follows the lab's, so whoever uses the vendor's index finds the lab's libraries too:

console
$ cat ~/vendor-index/index.toml
# a vendor's index: its own kinds, and it follows the lab's
schema  = 1
name    = "vendor"
follows = ["~/lab-index"]

[package.kinds]
source      = "file://~/remotes/vendor-kinds.git"
description = "A vendor's real kinds, with its own tuning"
console
$ fobis index add vendor ~/vendor-index
vendor: 1 package(s), dir index
Added index vendor = ~/vendor-index to ~/.config/fobis/config.ini
console
$ fobis index list
lab              dir   user     local                      ~/lab-index
vendor           dir   user     local                      ~/vendor-index

Every package of every index, qualified by the index's name:

console
$ fobis search
lab:kinds                    file://~/remotes/kinds.git
    Portable real kinds
lab:vectors                  file://~/remotes/vectors.git
    Small vectors of reals
vendor:kinds                 file://~/remotes/vendor-kinds.git
    A vendor's real kinds, with its own tuning

The lab's index is registered directly and followed by the vendor's: it is read once. kinds is in both indexes, from two different sources; the next chapter shows what that means when adding it.

What you learned

Seed indexes, fobis index build, fobis index check (--online), index add, index list, follows, qualified names INDEX:NAME. Reference: Index format, index.

Next: find, add and remove.