libreitalia
/
loaih
7
0
Fork 0
Code Issues 7 Pull Requests Packages Releases 5 Wiki Activity

Updated documentation with core concepts of the script. Updated all the pages to link the core concepts.

Emiliano Vavassori 2024-03-09 17:31:38 +01:00
parent 33af1af08b
commit 317f8bab1b
7 changed files with 214 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
Batch.md

@ -23,7 +23,8 @@ indicated in the YAML file.
### Basic structure ###
The file requires exactly **two** sections, one called `data` and the other one called `builds`.
The file requires exactly **two** sections, one called `data` and the other
one called `builds`.
### `data` section ###
@ -92,7 +93,6 @@ The script would build all the AppImages silently by default (and likely,
seemingly stuck); if you need to follow the building process, use the `-v` (or
`--verbose`) flag, which is the only option available for the `batch` verb.
## Remote repositories ##
If the parameter `repo` in the `data` section refers to a remote location,
@ -104,6 +104,7 @@ host you will indicate in `remote_host` for the user you plan to use to build
the AppImages with; also, ensure passwordless login can be performed (using
SSH private/public key pairs).
---
[Home](Home.md) — [Prerequisites](Prerequisites.md) — [Installation](Install.md) — [Usage - versions](Version.md) — [Usage - manual build](Build.md)
[Home](Home.md) — [Prerequisites](Prerequisites.md) —
[Installation](Install.md) — [Core concepts](Concepts.md) —
[Usage - versions](Version.md) — [Usage - manual build](Build.md)

4
Build.md

@ -73,4 +73,6 @@ quite explicit at this point; use it if you would like to build the same
version but with different options consecutively).
---
[Home](Home.md) — [Prerequisites](Prerequisites.md) — [Installation](Install.md) — [Usage - versions](Version.md) — [Usage - batch build](Batch.md)
[Home](Home.md) — [Prerequisites](Prerequisites.md) —
[Installation](Install.md) — [Core concepts](Concepts.md) —
[Usage - versions](Version.md) — [Usage - batch build](Batch.md)

171
Concepts.md Normal file

@ -0,0 +1,171 @@
# Core concepts of the script #
This page describes some core concepts behind the options of `loaih`.
## Manual builds versus bulk/batch builds ##
The `loaih` script can be used to produce a single, personal release of
LibreOffice packaged as AppImage (that will hardly be shared with everyone
else), as well as a full set of AppImages that can be shared with other people
for ease of consumption.
The single manual build is implemented with the `build` verb, while the
batch/bulk builds is supported with the `batch` verb of the `loaih`
command.
Since the two use cases are largely different, when developing `loaih` we
chose to distinguish the default behaviour of the options of the command based
on the verb.
The concepts behind the options available to both `build` and `batch` verbs
are explained in the rest of this page; the actual use of the two verbs is
explained in the relative pages: [Usage - manual build](Build.md) and [Usage -
batch build](Batch.md).
## Language support ##
The `loaih` script can include in your AppImage the language support you
prefer, by the use of the `--languages` option, or in short `-l`.
You can specify a single translation of LibreOffice, in addition to the
standard English, to be included in your build like:
loaih build daily -l 'zh-CN'
Or, you can provide a set of languages to include in a similar way:
loaih build daily -l 'pt,pt-BR'
The command recognises, also, three different sets of languages:
* `basic`, which includes just English and British English;
* `standard`, which includes English, Arabic, German, British English,
Spanish, French, Japanese, Korean, Portuguese, Brasilian Portuguese,
Russian, Standard Chinese and Taiwanese Chinese;
* `full`, which includes all the languages supported by LibreOffice at the
time of the specific release.
They can be used like:
loaih build daily -l standard
The default value, both for `build` and `batch` verbs, for the `--languages`
option is `basic`.
## Offline help ##
The `loaih` script will **not** include, by default, the offline help pages
for the chosen release, for both the `build` and `batch` verbs.
However, you can change the behaviour of the `build` verb using the
`--offline-help` option, or in short `-o`: when used, this option will honor
the value of the `--languages` option and include the help pages for all the
languages that have been selected by the user.
## Updatability ##
Updatability for an AppImage means to provide support to use the
[zsync2](https://github.com/AppImageCommunity/zsync2) utility to update a
previously downloaded AppImage. This tool permits to avoid re-downloading the
entire AppImage file, but to leverage the webserver to send only the different
chunks of the AppImage file from the local version.
Since the size of the AppImages are different based on language support,
offline help pages inclusion and so on, using `zsync2` to download a newly
built image is not always beneficial.
For an AppImage to be updatable means that the newly built AppImage has to be
publicly available on a web server that supports downlads in chunks, the
presence in the same folder of the AppImage file of a specific `.zsync` file
and the usage, by the final user, of the `zsync2` tool.
By default, the `loaih` script **does not** build an updatable AppImage when
using the `build` verb (manual build), however it does when using
the `batch` verb instead.
To revert the default behaviour of the `build` verb, you can use the
`--updatable` option (in short, `-u`), which forces `loaih` to build also the
`.zsync` file required to update a previous AppImage.
## Portability ##
The `loaih` command can produce AppImages that uses a different profile path
than the default LibreOffice one --- this is jergally known as "portable"
AppImage.
Portable versions greatly help when debugging an issue in a specific version
of LibreOffice and the debugger wants to be sure to exclude his own personal
settings of LibreOffice when doing so.
The `loaih` command builds, for both the `build` and `batch` verbs, an
AppImage that is **not** considered "portable": which means it uses the
default profile folder (which, for documentation purposes, is
`~/.config/libreoffice/4/user`).
If you want to build a "portable" version of an AppImage, be sure to include
with the `build` verb the option `--portable` (in short, `-p`): this will
change the profile path of the user settings of the LibreOffice AppImage to
`~/.config/libreoffice/<major-version>/user` folder.
## Signing ##
When releasing an AppImage, the developer can choose to sign the AppImage with
his own GPG signature.
`loaih` can obviously sign your AppImage using your default GPG key, however
it **does not** do it by default with the `build` verb (we assume not everyone
would have the necessity to sign the AppImage, nor everyone possesses a valid
GPG key). With the `batch` verb it does by default, instead.
If you want to sign your AppImage with your default GPG key, be sure to add
the option `--sign` (or in short `-s`).
## Checksums ##
When releasing a large file (like the LibreOffice AppImages are), developers
usually choose to provide a checksum of the file produced by commonly known
hashing algorithms. Of course, this is not needed when you are building an
AppImage on your own machine for your own use.
As such, the `batch` verb produces checksums for each of the file produced by
the build process; instead, the `build` verb **does not** by default.
If you want your AppImage to be accompanied with its own checksums, you can
provide the command with the `--checksums` option (in short, `-e`): `loaih`
will build your AppImage and produce an `.md5` file of each of the output
file, which contains the checksum for the file with MD5 algorithms.
You can then check your built AppImage for example with:
md5sum -c LibreOffice-24.2.0.3.basic-x86_64.AppImage.md5
## Keeping downloads ##
When releasing a great number of similar AppImages, all starting from the same
sources, as in the case of `batch` builds, keeping the downloads between
single builds will allow a great deal of bandwith saving and, in general,
optimize the release process.
This is however a very different approach than when building a single version
for your own purposes: you just need the built AppImage, and you don't care
about the sources once the build process is finished.
This is reflected in the behaviour of the two verbs of `loaih`, where:
* the `batch` verb will retain all the downloaded files;
* the `build` verb instead will remove the download folder as soon as it is
finished building your version.
If you want to keep your downloads when manually building your AppImage, you
can pass the option `--keep-downloads` (or `-k` in short) to preserve the
sources once your AppImage has been built: this is especially useful if you
want two slightly different versions of the same LibreOffice version as
AppImage (for example, if you want a version with the help pages and one
without).
If you want to customise the position inside your filesystem of the download
folder, you can also use the option `--download-path` (in short `-d`). This is
honored in any case, even if you don't want to keep your downloads after the
build.
---
[Home](Home.md) &mdash; [Prerequisites](Prerequisites.md) &mdash; [Installation](Installation.md) &mdash; [Usage - versions](Version.md) &mdash; [Usage - manual build](Build.md) &mdash; [Usage - batch build](Batch.md)

1
Home.md

@ -8,6 +8,7 @@
* [Prerequisites](Prerequisites.md)
* [Installation](Install.md)
* [Core concepts](Concepts.md)
* [Usage - versions](Version.md)
* [Usage - manual build](Build.md)
* [Usage - batch build](Batch.md)

23
Install.md

@ -8,25 +8,21 @@ You can build `loaih` from the sources in [this same
site](https://git.libreitalia.org/libreitalia/loaih/).
1. Clone the repository:
```
git clone https://git.libreitalia.org/libreitalia/loaih.git
```
2. Enter the directory with the sources:
```
cd loaih
```
3. Build sources and distribution files:
```
python3 setup.py bdist
```
4. If you have permissions (e.g. with `sudo`), you can install `loaih`
system-wide:
```
sudo python3 setup.py install
```
## From Releases ##
@ -38,14 +34,12 @@ section.
[Release](https://git.libreitalia.org/libreitalia/loaih/releases) page and
download the relative `.whl` file (e.g. `loaih-1.3.3-py3-none-any.whl`);
2. Ensure you have the `wheel` package installed in your system:
```
pip install wheel
```
3. Use `pip` to install the wheel you downloaded:
```
pip install /path/to/loaih-1.3.3-py3-none-any.whl
```
## From PyPI ##
@ -58,7 +52,6 @@ Upgrading to new versions of `loaih` is easier with `pip`, also:
pip install --upgrade loaih
## Test that `loaih` works ##
Just execute `loaih` from the command line with any further options:
@ -66,4 +59,6 @@ Just execute `loaih` from the command line with any further options:
loaih
---
[Home](Home.md) &mdash; [Prerequisites](Prerequisites.md) &mdash; [Usage - versions](Version.md) &mdash; [Usage - manual build](Build.md) &mdash; [Usage - batch build](Batch.md)
[Home](Home.md) &mdash; [Prerequisites](Prerequisites.md) &mdash;
[Core concepts](Concepts.md) &mdash; [Usage - versions](Version.md) &mdash;
[Usage - manual build](Build.md) &mdash; [Usage - batch build](Batch.md)

4
Prerequisites.md

@ -17,4 +17,6 @@ installed on your machine:
official websites.
---
[Home](Home.md) &mdash; [Installation](Install.md) &mdash; [Usage - versions](Version.md) &mdash; [Usage - manual build](Build.md) &mdash; [Usage - batch build](Batch.md)
[Home](Home.md) &mdash; [Installation](Install.md) &mdash;
[Core concepts](Concepts.md) &mdash; [Usage - versions](Version.md) &mdash;
[Usage - manual build](Build.md) &mdash; [Usage batch build](Batch.md)

21
Version.md

@ -1,23 +1,26 @@
# Usage - versions #
`loaih` can be used to find out information about a specific LibreOffice version; the script parses the [official LibreOffice download page](https://www.libreoffice.org/download/download-libreoffice/) and, in specific cases like daily builds, infers their availability from other known repositories.
`loaih` can be used to find out information about a specific LibreOffice
version; the script parses the [official LibreOffice download
page](https://www.libreoffice.org/download/download-libreoffice/) and, in
specific cases like daily builds, infers their availability from other known
repositories.
`loaih getversion` can be used as:
loaih getversion 5.4
to receive the following information:
```
query: 5.4
version: 5.4.7.2
x86: https://downloadarchive.documentfoundation.org/libreoffice/old/5.4.7.2/deb/x86/
x86_64: https://downloadarchive.documentfoundation.org/libreoffice/old/5.4.7.2/deb/x86_64/
```
The *query* line would report each argument for the `getversion` verb (see
below in *Multiple queries*); the *version* is the full version of
LibreOffice matching the query; the *x86* and *x86_64* would provide URLs to
download all the needed archives to build the AppImage.
below in *Multiple queries*); the *version* is the full version of LibreOffice
matching the query; the *x86* and *x86_64* would provide URLs to download all
the needed archives to build the AppImage.
## Textual queries ##
@ -36,7 +39,6 @@ today, and the daily build for yesterday;
indicated date (in the format 4-digits year, 2-digits month, 2-digits day
number); for a working example, 20231231 for the December 31st, 2023.
## Fallback to current for missing daily versions ##
If the daily upstream version has not been built today (e.g. likely between
@ -66,6 +68,7 @@ a JSON output:
loaih getversion fresh -j
---
[Home](Home.md) &mdash; [Prerequisites](Prerequisites.md) &mdash; [Installation](Install.md) &mdash; [Usage - manual build](Build.md) &mdash; [Usage - batch build](Batch.md)
[Home](Home.md) &mdash; [Prerequisites](Prerequisites.md) &mdash;
[Installation](Install.md) &mdash; [Core concepts](Concepts.md) &mdash;
[Usage - manual build](Build.md) &mdash; [Usage - batch build](Batch.md)