matthiasbeyer/imag
1
0
Fork 0
Code Releases Activity

Rephrase architecture doc.

Browse source
This commit is contained in:
Matthias Beyer 2017-10-14 21:35:55 +02:00
parent b942b9702d
commit 6068f2b52d
1 changed files with 23 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
doc/src/01010-architecture.md
View file

@ -1,7 +1,8 @@
# Architecture of the imag code
The imag codebase has a rather simple overall architecture. But before
introducing the reader to it, a few things have to be introduced.
The imag codebase has a rather simple overall architecture.
In this chapter the types of crates, architecture of an imag module
and the type structure are described.
## Crate types
@ -11,7 +12,7 @@ project.
First of all, there are core crates. These crates provide the very core of imag
and almost all other crates use them:
* libimagstore - The imag store is the abstraction overbthe filesystem. It
* libimagstore - The imag store is the abstraction over the filesystem. It
provides primitives to get, write and manipulate store entries and their
header information.
* libimagrt - The runtime library, which provides functionality to create a
@ -27,13 +28,15 @@ extensional functionality for the types from libimagstore. For example, there is
"libimagentrylink" which provides functionality to link two entries in the
store.
The next kind of crate is the one that offers end-user functionality for a imag
aspect, for example "libimagtodo" provides functionality to track todos.
The third kind of crate is the one that offers end-user functionality for a imag
domain, for example "libimagtodo" provides functionality to track todos.
And last, but not least, the commandline frontend crates provide the user
interface. These are the kind of crates that are not library crates, but
binaries.
Besides these, there are some other utility crates.
## Architecture of an imag module
With the things from above, a module could have the following architecture:
@ -62,24 +65,29 @@ With the things from above, a module could have the following architecture:
+-----------------------------------+---------+
```
The foundation of all imag modules is the store, as one can see from the image.
Above this there is the libimagrt, which provides the basic runtime and access
to the `Store` object. Cross-cutting, there is the error library (and possibly
The foundation of all imag modules is the store, as one can see in the image.
Above the store library there is the libimagrt, which provides the basic runtime
and access to the `Store` object.
Cross-cutting, there is the error library (and possibly
the util library, but we do not care about this one here), which is used through
all levels. The highest level of all imag modules is the commandline interface
on top of the domain library. In between can be any number of entry extension
libraries, or none if not needed.
Theoretically, the commandline interface crate could be replaced to build a
terminal user interface, graphical user interface or web interface.
## Types
The imag core, hence the libimagstore, libimagrt and libimagerror, provide a set
of types that a user (as in a library writer) should be aware of.
First of all, there is the Runtime type which is provided by the libimagrt. It
First of all, there is the `Runtime` type which is provided by the libimagrt. It
provides basic access to whether debugging or verbosity is enabled as well as
the most important core object: The `Store`.
It is provided by the libimagstore library, the heart of everything.
The `Store` type is provided by the libimagstore library, the heart of
everything.
When interacting with the store, two types are visible: `FileLockEntry` and
`Entry` whereas the former derefs to the latter, which basically means that the
@ -93,13 +101,11 @@ header and so on. Extensions for its functionality are implemented on this type,
not on the `FileLockEntry`.
The `Entry` provides access to its header, which is a `toml::Value`, where toml
is the toml-rs crate (external project). Conveniance functionality is provided
is the toml-rs crate (external project). Convenience functionality is provided
via the `toml-query` crate, which is an external project which was initiated and
extracted from the imag project.
Error types are also important. All errors in the imag prijects are generated by
libimagerror usage and are interoperable. User code hardly handles the actual
`Error` type but its inner one, `ErrorKind`, which is an enum where each member
can be mapped to a representing text. Imag error types do never contain payload
(they can via extensions, though it is not really practical and there is no
usage for it).
Error types are also important.
All errors in imag projects should be created with `error-chain`.
libimagerror provides functionality to enhance the experience with `Result`
types and general tracing of errors.