Sources
Hoa distributes the main following projects:
Central
: the set of all Hoa libraries,Library/*
: isolated standard libraries,Hoathis/*
: isolated user libraries (maintained by Hoa).
There is different ways to install Hoa: fully (with
the central) or partly (libraries independently), and
widely (on the system) or locally (in an
application). In the case of a wide installation and for
all systems adopting the
Filesystem Hierarchy
Standard (at least in the 2.2 version), Hoa will prefer to be installed
in the /usr/local/lib/Hoa/
directory. For other systems, like
Windows, Hoa will prefer to be installed in the
C:\Program Files\Hoa\
.
Table of contents
Dependency manager (Composer)
To manage dependencies between libraries of Hoa, we recommend the
Composer tool. All dependencies
managed by Composer are registered by the
Packagist repository
under the names
hoa/library
and
hoathis/library
. Thus, for example, to install the
Hoa\Websocket
library, we will have to write in the
composer.json
file:
{
"require": {
"hoa/websocket": "~3.0"
}
}
Then, to install dependencies:
$ composer install
It is recommended to read the documentation of Composer if you are not familiar with this tool.
To test the installation has succeeded:
<?php
require_once 'vendor/autoload.php';
var_dump(HOA); // bool(true)
Version manager (Git)
Hoa uses Git for all its projects. The
index of repositories can be found at the address:
git.hoa-project.net. Thus to get
sources of the
Central
project:
$ git clone https://git.hoa-project.net/Central.git Hoa.central
To get a library, for example Hoa\Websocket
:
$ git clone https://git.hoa-project.net/Library/Websocket.git Hoa/Websocket
It is recommended to read the documentation of Git if you are not familiar with this tool.
If you prefer a wide and full installation with the central, without neglecting the recommendation about Hoa localisation, you could use a symbolic link:
$ git clone https://git.hoa-project.net/Central.git /usr/local/lib/Hoa.central
$ ln -s /usr/local/lib/Hoa.central/Hoa /usr/local/lib/Hoa
Mirrors exist for the majority of projects, notably
Github,
Gitlab and
Pikacode. Names of projects
are identical as much as possible. The most important difference is for
libraries: there is no
Library/
prefix, or
Hoathis/
is replaced by Hoathis-
. Thus:
$ git clone https://github.com/hoaproject/Websocket.git
Mirrors are permanently synchronized, you will never have a difference.
To test the installation has succeeded:
<?php
require_once '/usr/local/lib/Hoa/Consistency/Prelude.php';
var_dump(HOA); // bool(true)
Structure of a library
Here is the structure of a library:
- sources at the root,
Bin/
, for the binaries,Documentation/
, for chapters of the hack book (documentation),Test/
, for the tests,README.md
, for an english description with usual examples,composer.json
, for the dependencies.
Binaries are accessible via the command: hoa
library:command
. For example, for
Hoa\Protocol\Bin\Resolve
, we will write: hoa
protocol:resolve
.
For the moment, tests are under migration!
Thank
you for your patience.
Rush Release
Hoa uses a release system called Rush Release, standing for Rolling Und ScHeduled Release. This section explains this system, that, despites its appearence, is very close to what is daily met while answering to the particular needs of the Hoa project.
Development and maturation
During its life, a library goes through three different states:
- the beta state represents a library under development, under writing,
- the RC (standing for Release Candidate) represents a library with a frozen API, a mature code; it is therefore intensively tested by several users to try the code and its API; once validated, it goes to the next state,
- the finalized state represents a finalized library; then its release cycle can start.
Release cycle
Once a library has been finalized, its release cycle can
start. Hoa uses a cycle called
Rolling Release.
It means that the main branch, master
, permanently contains the
latest version. No need to wait the release of a new
version in order to have the latest security or performances fixes, or the
latest new features: the main branch provides them
immediately. (Detail: Hoa applies part- and true-rolling
release).
However, some softwares used to install Hoa do no take this approach into account, or this approach does not fit into all environments or usages. That's why Hoa also uses another release cycle called Scheduled-based Release. Rules are the following:
- each 6 weeks, if at least one patch has been applied on the main branch, a new snapshot is created,
- before 6 weeks, if at least one critical or significant patch has been applied, a new snapshot is created.
Snapshots take the form of tags in Git repositories.
They have the following syntax:
x.YY.mm.dd
, where
x
is the master compatibility number (detailled
hereinafter), YY
is the year (starting from 2000, also
called Rush Epoch), mm
is the month and finally
dd
is the day.
The master compatibility number (MCN) represents the
number of time where the backward compatibility could not be ensured, in
other words where it is not possible to apply an update without any risk (we
also speak about backward compatibility break, BC break). Before a library
to reach the finalized state, its MCN is set to 0. Next, it is set to 1,
then it increases when needed. For instance, the snapshot of the day could
be 1.19.02.17
.
Thus, to use the latest snapshot of the Hoa\Websocket
library, you will have to write in your composer.json
file:
{
"require": {
"hoa/websocket": "~3.0"
}
}
And to use the latest available version, you will have to write:
{
"require": {
"hoa/websocket": "~3.0@dev"
}
}
The tilde
operator, or the next significant release operator, in Composer is
equivalent to >=3.0,<4.0
, being the latest possible
version for the same MCN.
PHP versions
Hoa supports all PHP versions greater or equal to the latest maintained version by the PHP Group. We talk about the lowest required PHP version (LRPV). Even if Hoa is compatible with older versions, libraries will not run on them deliberately. Consequently, each time a PHP version dies, it increases the MCN of each libraries.
It is possible to know the LRPV by reading the
composer.json
file of Hoa\Consistency
. Currently, Hoa supports all
versions greater or equal to 5.5.