Matthias Beyer
eeccd148f3
The title might be a bit inaccurate, but I cannot think of something
better.
Before the change
=================
Before this change, we had a compiletime backend for the store. This
means that the actual filesystem operations were compiled into the store
either as real filesystem operations (in a normal debug or release
build) but as a in-memory variant in the 'test' case.
So tests did not hit the filesystem when running.
This gave us us the possibility to run tests concurrently with multiple
stores that did not interfere with eachother.
Problem
=======
This approach worked perfectly well until we started to test not the
store itself but crates that depend on the store implementation.
When running tests in a crate A that depends on the store, the store
itself was compiled with the filesystem-hitting-backend.
This was problematic, as tests could not be implemented without hitting
the filesystem.
After the change
================
After this change, the backend code is injected into the store via
dependency injection (the `Store::new()` function automatically uses the
filesystem-backend).
The store can be created with a the in-memory backend when running tests
now.
Implementation
==============
The implementation of this is rather stupid, despite the big diff in
this commit.
Lets have a look at the `Store` code changes first and then we'll
discuss the `file_abstraction` changes this commit introduces.
libimagstore::fs_abstraction
----------------------------
The filesystem was abstracted via a trait `FileAbstraction` which
contains the essential functions for working with the filesystem.
Two implementations are provided in the code:
* FSFileAbstraction
* InMemoryFileAbstraction
whereas the first actually works with the filesystem and the latter
works with an in-memory HashMap that is used as filesystem.
Further, the trait `FileAbstractionInstance` was introduced for
functions which are executed on actual instances of content from the
filesystem, which was previousely tied into the general abstraction
mechanism.
So, the `FileAbstraction` trait is for working with the filesystem, the
`FileAbstractionInstance` trait is for working with instances of content
from the filesystem (speak: actual Files).
The `FileAbstraction` trait requires a function to be implemented that
can be used to create a `FileAbstractionInstance` object from it.
In case of the `FSFileAbstractionInstance`, which is the implementation
of the `FileAbstractionInstance` for the actual filesystem-hitting code,
the underlying resource is managed like with the old code before.
The `InMemoryFileAbstractionInstance` implementation is corrosponding to
the `InMemoryFileAbstraction` implementation - for the in-memory
"filesystem".
The implementation of the `get_file_content()` function had to be
changed to return a `String` rather than a `&mut Read` because of
lifetime issues.
This change is store-internally and the API of the store itself was not
affected.
libimagstore::store::Store changes
----------------------------------
So, first we need to make sure that the store knows the actual backend.
Therefor, the `new()` method was renamed to `new_with_backend()` and got
another parameter: the backend implementation.
A new `new()` function was created for convenience and
backwards-compatibility with the rest of the imag codebase (and also
because nobody wants to pass the backend manually all the time).
As the backend is abstracted via a trait, and the store should not
change its interface, the new `Store` member was introduced inside a
`Box`.
All calls (`remove_file()`, `copy()`, `rename()` and `create_dir_all()`)
were refactored from `FileAbstraction::*` calls into `self.backend.*`
calls.
libimagstore::store::StoreEntry changes
---------------------------------------
The `StoreEntry` type is constructed in the store internally for holding
a `StoreId` object as well as some status and the file abstraction code.
This object is constructed via a `new()` function that got a new
parameter: a `&Box<FileAbstraction>` to the backend abstraction the
store uses.
This backend is now used to create a new `FileAbstractionInstance`
object for the `StoreEntry`.
Also the `StoreEntry::get_entry()` code had to be adapted to the new
`Entry::from_str()` function interface.
This commit message is partially added as comment in the code.
Signed-off-by: Matthias Beyer <mail@beyermatthias.de>
|
||
|---|---|---|
| .imag-documentation | ||
| bin | ||
| doc | ||
| imag-bookmark | ||
| imag-counter | ||
| imag-diary | ||
| imag-link | ||
| imag-mail | ||
| imag-notes | ||
| imag-ref | ||
| imag-store | ||
| imag-tag | ||
| imag-todo | ||
| imag-view | ||
| libimagannotation | ||
| libimagbookmark | ||
| libimagcounter | ||
| libimagdiary | ||
| libimagentrydatetime | ||
| libimagentryedit | ||
| libimagentryfilter | ||
| libimagentrylink | ||
| libimagentrylist | ||
| libimagentrymarkdown | ||
| libimagentrytag | ||
| libimagentryview | ||
| libimagerror | ||
| libimaginteraction | ||
| libimagmail | ||
| libimagnotes | ||
| libimagref | ||
| libimagrt | ||
| libimagstore | ||
| libimagtimeui | ||
| libimagtodo | ||
| libimagutil | ||
| tests | ||
| .editorconfig | ||
| .gitignore | ||
| .travis.yml | ||
| Cargo.toml | ||
| CONTRIBUTING.md | ||
| default.nix | ||
| imagrc.toml | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
imag - imag-pim.org
imag is a commandline personal information management suite.
This application is in early development. There are some things that work, but we do not consider anything stable or usable at this moment. Feel free to play around anyways.
Goal / What is imag?
Our (long-term) goal is to
Create a fast, reliable commandline personal information management suite which covers all aspects of personal information management, consists of reusable parts and integrates well with known commandline tools.
imag is a PIM helper. We do not actually implement the PIM functionality, but try to interface with existing PIM tools (via their API or via some standard format they use, e.g. vcard) to make the data they manage linkable and queryable in an uniform way.
imag consists of modules (e.g. imag-notes, imag-tag, imag-view), where
each module covers one PIM aspect.
The initial approach is to use one PIM tool for one module.
So you can use imag-todo with taskwarrior,
imag-mail with Maildirs and imag-calendar with
icalendar files.
Building/Running
Here is how to try imag out.
imag is a suite/collection of tools (like git, for example) and you can
build them individually.
All subdirectories prefixed with "libimag" are libraries.
All subdirectories prefixed with "imag-" are binaries and compiling them will
give you a commandline application.
Building
We use make to automate the build process.
Make sure to not include some -j 8 arguments, this will not work as you
might think!
There are several targets for each of the sub-crates in the Makefile:
| Target | Multi | Purpose | Example |
|---|---|---|---|
| all | Build everything, debug mode | make all |
|
| bin | Build all binaries, debug mode | make bin |
|
| lib | Build all libraries, debug mode | make lib |
|
| lib-test | Test all libraries | make lib-test |
|
| imag-bin | Build only the imag binary, debug mode |
make imag-bin |
|
| clean | Remove build artifacts | make clean |
|
| update | Run cargo update |
make update |
|
| check-outdated | Run cargo outdated |
make check-outdated |
|
| check | * | Run cargo check |
make check |
| install | * | Build everything, release mode, install | make install |
| release | * | Build everything, release mode | make release |
The Multi targets are callable for each sub-crate. For example you can call
make imag-store-check to run cargo check on the imag-store crate.
Running
After you build the module you want to play with, you can simply call the binary
itself with the --help flag, to get some help what the module is capable of.
If you installed the module, you can either call imag-<modulename> (if the
install-directory is in your $PATH), or install the imag binary to call imag <modulename> (also if everything is in your $PATH).
Staying up-to-date
We have a official website for imag, where I post release notes. There is no RSS feed, though.
We also have a mailinglist where I post updates and where discussion and questions are encouraged.
There is a blog series which gets an update once a month on my blog, where entries are tagged "imag". I also post non-regular posts about imag things there.
I also post these blog posts on reddit and submit them to this-week-in-rust.
Documentation
This is a hobby project, so sometimes things are not optimal and might go unrecognized and slip through. Feel free to open issues about things you notice!
Though, we have some documentation in the ./doc subtree which can be compiled to PDF or a website. These docs are not published anywhere and are not even integrated into our CI, so it might be broken (though it's unlikely). Developer documentation is also available online on github.io and on docs.rs, though they might be a bit outdated.
Please contribute!
We are looking for contributors!
There is always a number of complexity/easy tagged issues available in the issue tracker you can start with and we are open to questions!
Feel free to open issues for asking questions, suggesting features or other things!
Also have a look at the CONTRIBUTING.md file!
Contact
Have a look at our website where you can find some information on how to get in touch and so on.
Feel free to join our new IRC channel at freenode: #imag or our mailinglist.
License
We chose to distribute this software under terms of GNU LGPLv2.1.