dlib — Documentation — Creating repositories

Index:

  1. What is a repository?
  2. How the structure of a dlib repository is?
  3. The index file
  4. The script files
  5. Publishing a repository
  6. Maintaining a repository

Here, you'll learn how to create a dlib repository, how to make it public and how to mantain it.

1. What is a repository?

A dlib repository is a place on internet that dlib can scan to get scripts.

An example of a repository is https://elitees.github.io/dlib-index/

There's no HTML there, but there's a file in https://elitees.github.io/dlib-index/index that contains a dlib script that dlib can read to extract where the scripts are.

You can check the code of that repository in https://github.com/elitees/dlib-index.

2. How the structure of a dlib repository is?

The structure of a dlib repository is quite simple. It consists of a main index file that contains the list of available scripts and their locations.

Here's a tree of that repository:

dlib-index/
├── index
├── mank-git/
│   └── latest.dls
├── test/
│   └── v0.0.1.dls
└── mank-source/
    └── v0.1.0.dls

3. The index file

In that example, the main index file is index, which contains the list of available scripts and their locations. The other files are the scripts themselves.

Here's an example of the index file:

- script "mank-git" "mank-git/" "latest.dls"
- script "test" "test/" "v0.0.1.dls"
- script "mank-source" "mank-source/" "v0.1.0.dls"

The index file uses a dlib-like syntax to define each script and its location. The first field of the script command is the name of the script, which the user is going to use doing dlib install script-name. The second field is the path to the script directory, and the third field is the default filename of the script if the user doesn't specify a version.

4. The script files

The scripts are saved on the folder where the index file says. dlib is going to read the index file, then it processes the filename and version in order to locate the script. Here's a graphical way explaining it:

user: dlib install mank-git
-> dlib: reads local script index
-> dlib: detects that "mank-git" script is located at "example.com/dlib-index/mank-git/" and as the user didn't specify a version it should use "latest.dls"
-> dlib: reads "example.com/dlib-index/mank-git/latest.dls"
-> dlib: processes the script and runs it
user: dlib install mank-source:v0.1.0
-> dlib: reads local script index
-> dlib: detects that "mank-source" script is located at "example.com/dlib-index/mank-source/" and as the user specified the version "v0.1.0" it should use "v0.1.0.dls"
-> dlib: reads "example.com/dlib-index/mank-source/v0.1.0.dls"
-> dlib: processes the script and runs it

Normally you wouldn't need to create those .dls files as you only mantain the repository, but if you need to create those files, read the creating scripts guide.

5. Publishing a repository

To publish a dlib repository, you need to make it accessible over the internet. You can use a static file hosting service like GitHub Pages, GitLab Pages, or any other service that allows you to host static files.

Then, you can let users add that repository by letting them know the path of the folder in which the index file is. If the file is at https://username.github.io/mydlib-repo/index the repository path is https://username.github.io/mydlib-repo/.

Users can access to it by running dlib --repository add https://username.github.io/mydlib-repo/.

6. Maintaining a repository

Once you have published your dlib repository, you need to maintain it by keeping the index file up to date with the latest scripts and their locations.

You should also know about new dlib updates as the syntax may change or require manual interventions to the scripts.