FoBiS.py

Appearance

8. quad as a package ​

In chapter 4 another project used quad through a path to its fobos. That works on one machine. To let anyone use quad by name, it becomes a package: a git repository with a version tag, listed in a package index. No server is involved: an index is a small file you publish wherever you like, and FoBiS reads several of them side by side.

Publish quad in your own index ​

quad gets a git repository and its first tag, v0.1.0, and a copy stands in for its public remote (~/remotes/quad.git). fobis publish --index adds the project to an index file, here a directory of yours:

console
$ fobis publish --index ~/my-index/index.toml --source file://$HOME/remotes/quad.git
Added quad in ~/my-index/index.toml (2 module(s))
console
$ cat ~/my-index/index.toml
schema = 1

[package.quad]
source = "file://~/remotes/quad.git"
provides = ["integrands", "quad_rules"]
builds = ["fobis", "make"]

The entry holds the source URL and the modules quad provides, read from its sources. It holds no version: the versions are the repository's tags, so tagging a release is publishing it.

Find a package ​

fobis index add registers the index in your user configuration (a project fobos can name indexes too, in an [indexes] section). Then the indexes are searched, by name, words or module:

console
$ fobis index add mine ~/my-index
mine: 1 package(s), dir index
Added index mine = ~/my-index to ~/.config/fobis/config.ini
console
$ fobis search --module quad_rules
mine:quad                    file://~/remotes/quad.git

fobis info reads the source itself: its versions, its build system and the modules of its newest version:

console
$ fobis info quad
quad  (file://~/remotes/quad.git)
  index     : mine
  license   : unknown
  build     : fobis, make
  versions  : v0.1.0
  modules   : integrands, quad_rules

Use it by name ​

A new project, survey, compares the two rules of quad on the sine:

fortran
!< A survey of quad's rules, using quad as a package added by name.
program survey
!< A survey of quad's rules, using quad as a package added by name.
use integrands, only : sine
use quad_rules, only : R8P, simpson, trapezoid
implicit none

real(R8P), parameter :: pi = acos(-1._R8P)

print '(A, F18.15)', 'trapezoid = ', trapezoid(sine, 0._R8P, pi, 64)
print '(A, F18.15)', 'simpson   = ', simpson(sine, 0._R8P, pi, 8)
endprogram survey
ini
[modes]
modes = gnu

[gnu]
compiler  = gnu
src       = ./src/
build_dir = ./build/
target    = src/survey.F90

[dependencies]
transitive = true

fobis add quad resolves the name through the indexes once, and writes the source URL into the fobos with a range starting at the newest version:

console
$ cd ~/survey && fobis add quad
Added quad = file://~/remotes/quad.git :: semver=^0.1.0
Run 'fobis fetch' to fetch it.
ini
[dependencies]
transitive = true
# added by fobis add from index mine
quad = file://~/remotes/quad.git :: semver=^0.1.0

From now on the fobos names the source, not the index: fetch and build never read an index, so the project keeps building if the index disappears. A name found in two indexes is refused, with the INDEX:NAME choices.

quad itself depends on PENF. transitive = true makes fetch read the fobos of each dependency and fetch its dependencies too, choosing for each package the highest minimum version required anywhere (Minimal Version Selection: the same answer tomorrow, whatever is published meanwhile):

console
$ cd ~/survey && fobis fetch
Cloning quad from file://~/remotes/quad.git
Checking out v0.1.0 for quad
Cloning penf from https://github.com/szaghi/PENF
Checking out v2.0.1 for penf
penf: v2.0.1 (required by quad)
Saved deps config to .fobis_deps/.deps_config.ini
Saved lock file to .fobis_deps/fobos.lock
console
$ cd ~/survey && fobis build --quiet && ./build/survey

Building src/survey.F90
Compiling .fobis_deps/quad/src/quad_rules.F90 serially
Compiling .fobis_deps/quad/src/integrands.F90 serially
Compiling src/survey.F90 serially
Linking build/survey
Target src/survey.F90 has been successfully built
trapezoid =  1.999598388640037
simpson   =  2.000269169948388

The lock records what each dependency resolved to and who required it:

console
$ cd ~/survey && grep -E "^\\[|resolved|required_by" .fobis_deps/fobos.lock
[quad]
resolved = v0.1.0
[penf]
resolved = v2.0.1
required_by = quad

A release without git ​

Some users download releases instead of cloning. fobis publish --archive writes the tarball of the latest tag and its entry in fortran-releases.toml, a manifest any static web server, object store or shared directory can serve:

console
$ fobis publish --archive ~/site/quad
Wrote ~/site/quad/quad-0.1.0.tar.gz and its entry in ~/site/quad/fortran-releases.toml (sha256 20d203fc68b21b1a...)
console
$ cat ~/site/quad/fortran-releases.toml
schema = 1
name = "quad"

[[release]]
version = "0.1.0"
archive = "quad-0.1.0.tar.gz"
sha256 = "20d203fc68b21b1accb41a7ba74e5d325710e5f6e26b06f3553884f318f58840"

That directory is a source like a git repository: fobis info, add and fetch read its manifest, and fetch checks every archive against its sha256:

console
$ fobis info ~/site/quad
quad  (~/site/quad)
  license   : unknown
  build     : fobis, make
  versions  : 0.1.0
  modules   : integrands, quad_rules

Install it for your compiler ​

A library is only usable with the compiler that built its module files. fobis pkg install builds a package from source with your compiler and files it under a toolchain key (compiler family, version, and a digest of its path and flags), with a pkg-config file, so any build system can link it:

console
$ fobis pkg install quad --bin-dir ~/bin
Building quad v0.1.0 with gfortran (gnu-13.4.0-de7b0728), fobis
Installed quad v0.1.0 for gnu-13.4.0-de7b0728 in ~/.fobis/pkgs/gnu-13.4.0-de7b0728/quad/0.1.0
  modules : quad_rules
  use it  : export PKG_CONFIG_PATH=~/.fobis/pkgs/gnu-13.4.0-de7b0728/quad/0.1.0/lib/pkgconfig
console
$ PKG_CONFIG_PATH=$(fobis pkg path quad --pkgconfig) pkg-config --cflags --libs quad
-I~/.fobis/pkgs/gnu-13.4.0-de7b0728/quad/0.1.0/include -L~/.fobis/pkgs/gnu-13.4.0-de7b0728/quad/0.1.0/lib -lquad

Both outputs depend on the machine (the key names the compiler and its path).

Finally, fobis audit reads the advisories each dependency publishes about its own versions (none here):

console
$ cd ~/survey && fobis audit
quad                 v0.1.0       ok
penf                 v2.0.1       ok

A public index ​

Your index can list your packages and follow others. fortran-index lists public FoBiS and fpm projects (catalogue): register it with fobis index add szaghi https://github.com/szaghi/fortran-index, or follow it from yours with follows = ["https://github.com/szaghi/fortran-index"].

What you learned

fobis publish, fobis index, fobis search, fobis info, fobis add, transitive = true, fobis pkg install, fobis audit. Reference: Packages and indexes.

Next: one fobos, many machines.