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-diary), 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 but imag-calendar with icalendar files.

Building/Running

Here goes how to try imag out.

imag is a suite/collection of tools and you can build them individually. All subdirectories prefixed with "libimag" are libraries for the respective binaries. 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 (as cargo is not (yet?) able to build several applications at once). Make sure to not include some -j 8 arguments, as cargo parallelizes the build process on its own. If you parallelize it with make, you end up with a really high load on your system.

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
check	*	Run cargo check	make check
clean	*	Remove build artifacts	make clean
install	*	Build everything, release mode, install	make install
release	*	Build everything, release mode	make release
update	*	Run cargo update	make update

The Multi targets are callable for each sub-crate. For example you can call make imag-bookmark-check to run cargo check on the imag-bookmark subcrate.

Running

To test out a single module, simply using cargo run -- <options> in the respective directory will do the trick. But you can also make <module> and call the binary on the commandline. For using it "normally", install the binaries as described above, as well as the imag-binary:

$> make install

The installation root of the binaries may not yet be in your $PATH. To see where this installation root is check out man cargo-install. To change the $PATH in bash:

$> PATH=$PATH:~/.cargo/bin
$> imag --help

To test, simply add --help to one of the above commands:

$> imag counter --help

Staying up-to-date

Despite we have a official site for imag, I do not push updates to this site, yet. Anyways, I post a blog articles about what happened in the last two weeks every other week.

You can find them on my personal blog, tagged "imag"

I also post these blog posts on reddit and submit them to this-week-in-rust.

From time to time I publish an article about imag which does not focus on some things that are happening, but rather about something more general.

Documentation

For detailed information, please read the documentation. You can either read the Markdown files or compile it to HTML/PDF using pandoc. Developer documentation is also available online on github.io.

Please note that the documentation is work in progress as well and may be 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.

This decision was made to ensure everyone can write applications which use the imag core functionality which is distributed with the imag source distribution.