A core tenet in elba’s functionality is the idea of resolutions. A resolution is a generic location from which some resource (a package or a package index) can be retrieved. Internally, elba distinguishes between two types of resolutions:
- A direct resolution refers to a direct location from which a resource (either a package or a package index) can be downloaded. Direct resolutions themselves can include references to tarballs (either on a network somewhere or located on disk), local directories on disk, or git repositories.
- An index resolution refers to an index from which information about a package’s location can be obtained. The location of the index itself must be a direct resolution.
A package can have (and is identified by) either a direct resolution or an index resolution. A package index is identified by its index resolution.
In order to refer to these types of direct resolutions, elba has its own simple syntax for “resolution strings”:
Each of the types of direct resolutions has its own syntax:
For a direct resolution which points to a tarball, the resolution string must start with the identifier
tar+and include a properly-formed URL with either the
https://(referring to a tarball on the network somewhere) or
file://(referring to a local tarball) schemas:
These are all valid: tar+http://example.com/asdf.tar.gz tar+https://example.com/asdf tar+file://../asdf.tar.gz
For a direct resolution which points to a directory on disk, the resolution string must start with the identifier
dir+and include a properly-formed path to a directory on disk:
These are all valid: dir+asdf dir+./asdf dir+../asdf/whatever/subfolder On Windows, these would be valid too: dir+C:\Users\John\etc
For a direct resolution which points to a git repository, the resolution string must start with the identifier
git+and provide the URL of the repository in question. Additionally, a git ref can be specified as part of the fragment of the URL:
These are all valid: git+https://github.com/example/doesnt-exist git+https://github.com/example/doesnt-exist#master <- use the master branch git+https://github.com/example/doesnt-exist#v1.0.0 <- use the "v1.0.0" tag git+https://github.com/example/doesnt-exist#a4e13343 <- use the commit "a4e13343" git+ssh://firstname.lastname@example.org/example/doesnt-exist <- using ssh instead of https
For an index resolution, the resolution string must start with the identifier
index+and include the direct resolution of the origin of the index:
These are all valid index+tar+http://example.com/asdf.tar.gz index+dir+../asdf/whatever/subfolder index+git+ssh://email@example.com/example/doesnt-exist#a4e13343