Technical Manual of the US-Common Layer

Organisation:

Copyright (C) 2019-2021 Olivier Boudeville

Contact:

about (dash) us-common (at) esperide (dot) com

Creation date:

Saturday, May 2, 2020

Lastly updated:

Monday, July 5, 2021

Version:

0.0.2

Status:

Stable

Dedication:

Users and maintainers of the US-Common layer.

Abstract:

The role of the US-Common layer (part of the Universal Server project) is to provide base elements on which the various Universal Services are built, notably:

  • the Universal Server itself: see US-Main
  • the Universal Webserver: see US-Web

We present here a short overview of these services, to introduce them to newcomers.

The next level of information is either to browse the US-Common API documentation or simply to read the corresponding source files, which are intensely commented and generally straightforward.

The latest version of this documentation is to be found at the official US-Common website (http://us-common.esperide.org).

This US-Common documentation is also available in the PDF format (see us-common-Layer-technical-manual-english.pdf), and mirrored here.

Table of Contents

Overview

The US-Common layer is the basis (lowest-level) of the Universal Server project.

Its purpose is to provide base elements on which the various Universal Services are built, notably:

We present here a short overview of these services, to introduce them to newcomers.

The next level of information is to read the corresponding source files, which are intensely commented and generally straightforward.

The project repository is located here.

Layer Stack

From the highest level to the lowest, as shown here, usually a software stack involving US-Common is structured that way:

The shorthand for US-Common is uc.

Facilities Provided by this Layer

These are mainly common services centralised here so that the various US applications can make use of them:

Licence

US-Common is licensed by its author (Olivier Boudeville) under the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of this license, or (at your option) any later version.

This allows the use of the US-Common code in a wide a variety of software projects, while still maintaining copyleft on this code, ensuring improvements are shared.

We hope indeed that enhancements will be back-contributed (ex: thanks to merge requests), so that everyone will be able to benefit from them.

Current Stable Version & Download

We prefer using GNU/Linux, sticking to the latest stable release of Erlang, and building it from sources, thanks to GNU make.

As mentioned, the single, direct prerequisite of US-Common is Ceylan-Traces, which implies in turn Ceylan-WOOPER, then Ceylan-Myriad and Erlang.

Refer to the corresponding Myriad prerequisite section for more precise guidelines, knowing that US-Common does not need modules with conditional support such as crypto or wx.

Using Cutting-Edge GIT

This is the installation method that we use and recommend; the US-Common master branch is meant to stick to the latest stable version: we try to ensure that this main line always stays functional (sorry for the pun). Evolutions are to take place in feature branches and to be merged only when ready.

Once Erlang is available, it should be just a matter of executing:

$ git clone https://github.com/Olivier-Boudeville/Ceylan-Myriad myriad
$ cd myriad && make all && cd ..

$ git clone https://github.com/Olivier-Boudeville/Ceylan-WOOPER wooper
$ cd wooper && make all && cd ..

$ git clone https://github.com/Olivier-Boudeville/Ceylan-Traces traces
$ cd traces && make all && cd ..

# Note the dash becoming an underscore, for OTP compliance:
$ git clone https://github.com/Olivier-Boudeville/us-common us_common
$ cd us_common && make all

Running a corresponding test just then boils down to:

$ cd test && make class_USScheduler_run CMD_LINE_OPT="--batch"

Should LogMX be installed and available in the PATH, the test may simply become:

$ make class_USScheduler_run

Support

Bugs, questions, remarks, patches, requests for enhancements, etc. are to be reported to the project interface (typically issues) or directly at the email address mentioned at the beginning of this document.

Please React!

If you have information more detailed or more recent than those presented in this document, if you noticed errors, neglects or points insufficiently discussed, drop us a line! (for that, follow the Support guidelines).

Ending Word

Have fun with US-Common!