The Amalthea Library is free software.
This library is distributed in the hope that it will be useful,
but without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose.


**Official repository**: [https://codeberg.org/os-18/amalthea](https://codeberg.org/os-18/amalthea)  

**Mirror:** [https://gitlab.com/os-18/amalthea](https://gitlab.com/os-18/amalthea)

---

## Amalthea

Amalthea is a small, general-purpose, Linux-specific library
for the D programming language.
It provides several useful functions.

**Library documentation:**  
[https://os-18.codeberg.page/amalthea/](https://os-18.codeberg.page/amalthea/)


## Features

The Amalthea library has been under development as a standalone project
since 2018. The project's goal is simple: over time, I have incrementally
implemented features that I found missing in D's standard library,
driven by the needs of my own projects.
For various reasons, it is Linux-oriented; it has not been tested
on other operating systems. Below are the modules I consider most useful.

### amalthea.fs

Among the especially useful features, this module provides efficient
implementations of `read()`/`write()`/`copy()`/`copyRecurse()`.
It includes `hardlink()` for creating links to files, a set of functions
for working with extended file attributes (`xattr`),
`truncate()` for changing file size, a custom directory reading mechanism.

Provides the `buildPath()`, `dirName()`, and `baseName()` functions.
Their behavior is equivalent to the corresponding functions in `std.path`,
but our implementations are several times faster.

### amalthea.sys

Among other things, this module provides functions for creating named pipes,
resolving user and group names from IDs and vice versa,
mounting and unmounting functions,
and facilities for file/anonymous memory mappings.
It implements UNIX signal handling.
Functionality for working with loop devices is also provided.

### amalthea.decimal

This module offers a straightforward implementation of fixed-point
decimal numbers (the `Decimal` struct) built on top of `BigInt` from Phobos.
A full set of basic arithmetic operations is implemented,
including exponentiation and logarithms.


### amalthea.dataprocessing

Contains several simple utilities for command-line argument handling,
a JSON serializer for structs, and a deserializer from JSON back to structs.
The `copyArray()` function is provided for copying arrays
with const-correctness and proper handling of structs that may have
copy constructors (the built-in `dup` does not always work correctly).
Occasionally one needs an associative array with predictable element order;
to satisfy that requirement, an `OrderedMap` struct is implemented.


### amalthea.fileformats

This module provides functions for file format recognition based on both file
signatures and extensions. Development of this module began when it became clear
that the MIME system on Linux is not reliable enough — it fails to recognize
formats such as TS (stream media container), DAV (CCTV video recording),
several Microsoft-specific formats, some MATLAB formats,
go.mod (Go module descriptor), PKT (Cisco Packet Tracer format), etc.
For this module to work, several hundred format descriptions are stored
in a separate file, `fileformats.json`, which is installed
into `/etc/amalthea-$DC/` (where `$DC` is the D compiler being used).
The module also supports traditional MIME-based file format detection.

### amalthea.encoding

This module provides an implementation of the KOI8R and KOI8U text encodings
(compatible with `std.encoding.EncodingScheme`),
and the `encodeText()` function (based on `libiconv`) to translate text
from any encoding to any other encoding.

---

## Ready-made packages

See
[this page](https://codeberg.org/os-18/os-18-docs/src/branch/master/OS-18_Packages.md).

The page contains information on how to install various packages,
including **Amalthea**.

---

## Build from source

### Preparing

You need to have at least one of the following compilers installed:

- [Digital Mars D Compiler](https://dlang.org/download.html#dmd)
- [LLVM D Compiler](https://wiki.dlang.org/LDC)
- [GNU D Compiler](https://www.gdcproject.org)

The library also depends on **libgio-2.0** and **libglib-2.0**.
These libraries are most likely already installed on your system.


### Compilation and installation

To build static and dynamic libraries using the **ldc2** compiler (default):

```bash
make
```

Installation (root privileges may be required):

```bash
make install
```

After that, the library for ldc2 is ready for use.


The Makefile contains variables:

* `DESTDIR` specifies the root directory for installing (empty by default);
* `PREFIX` specifies the base directory, such as `usr/local` or `usr`.

The installation directory is defined as `$(DESTDIR)/$(PREFIX)` in the Makefile.

You can install the library files in any directory.
For example, to install into `$HOME/.local`:

```bash
make install DESTDIR=$HOME PREFIX=.local
```

Uninstall:

```bash
make uninstall
```

If the project was installed in a non-default location,
use the corresponding paths:

```bash
make uninstall DESTDIR=$HOME PREFIX=.local
```

### Other compilers

The default compiler is **ldc2**.  
You can choose another compiler (for example, **dmd**):

```bash
make DC=dmd
```

Installing:

```bash
make install DC=dmd
```

Uninstalling:

```bash
make uninstall DC=dmd
```

---

## Feedback

For questions, suggestions, comments, or bugs reports, contact:

**tech.vindex@gmail.com**

Also use the repository service tools.

---
