imag/README.md

160 lines
5.8 KiB
Markdown
Raw Normal View History

2016-08-01 14:37:09 +00:00
# imag - [imag-pim.org](http://imag-pim.org)
2015-10-30 22:52:43 +00:00
2016-10-03 18:44:06 +00:00
`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.**
2016-07-30 10:33:55 +00:00
[![Build Status](https://travis-ci.org/matthiasbeyer/imag.svg?branch=master)](https://travis-ci.org/matthiasbeyer/imag)
[![Issue Stats](http://www.issuestats.com/github/matthiasbeyer/imag/badge/pr?style=flat-square)](http://www.issuestats.com/github/matthiasbeyer/imag)
[![Issue Stats](http://www.issuestats.com/github/matthiasbeyer/imag/badge/issue?style=flat-square)](http://www.issuestats.com/github/matthiasbeyer/imag)
2016-08-29 06:33:49 +00:00
[![license](https://img.shields.io/github/license/matthiasbeyer/imag.svg?maxAge=2592000?style=flat-square)]()
2016-10-03 18:44:06 +00:00
## What is this / Goal and Functionality
2016-10-03 18:44:06 +00:00
Our (long-term) goal is to
2016-10-03 18:44:06 +00:00
> 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.
2016-10-03 18:44:06 +00:00
We try to implement as many aspects of personal information management (PIM),
but re-use existing commandline tools.
We do this by tracking/referring to the data the tools create.
A user can now link pieces of data (from different tools), tag this data and
query/search this data using imag.
So `imag` is more like a data-mining helper than an actual PIM tool, but we
implement some of the PIM aspects directly in `imag`.
Parts of PIM (we call them "modules") that are already implemented and basically
working:
* todo (via taskwarrior, we track the tasks one creates in taskwarrior)
* diary
* notes
* bookmarks
* counter (just an example, nothing that usable)
Helper modules that come with `imag` but are not "PIM aspects":
* linking entries
* viewing entries
* tagging entries
* creating misc entries
* creating entries that refer to files/directories
## Building/Running
2016-10-03 18:44:06 +00:00
Here goes how to try `imag` out.
`imag` is a _suite_ 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.
2016-07-30 10:33:55 +00:00
### Building
By now, there are several targets in the Makefile, fulfilling following roles:
2016-10-03 18:44:06 +00:00
* `all` is the default and builds every crate in debug mode.
To build a single module, call `make <module>`, for example `make imag-store`.
* `release`, as the name implies, builds every module in release mode.
E.G.: `make imag-store-release` to build "imag-store" in release mode.
* `install` will install all commandline modules to the default installation
root (see `man cargo-install`).
To install a single module, run `make <module>-install`,
E.G.: `make imag-store-install`
* `bin`/`lib` are separate targets for either building all binaries or
libraries.
2016-10-03 18:44:06 +00:00
* `lib-test` runs `cargo test` for all libraries.
For testing a single library, E.G.: `make test-libimagstore`.
* `clean` will run `cargo clean` in every crate.
For cleaning a single crate, use `make imag-store-clean` for example.
* to build _only_ the `imag` binary, use the target `imag-bin`
2016-10-03 18:44:06 +00:00
(`imag-bin-release` for release build, `imag-bin-clean` for `cargo clean`ing).
### Running
To test out a single module, simply using `cargo run -- <options>` in the
2016-10-03 18:44:06 +00:00
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:
2016-10-03 18:44:06 +00:00
```
$> make install
```
2016-10-03 18:44:06 +00:00
The installation root of the binaries may not yet be in your $PATH.
2016-10-04 11:49:41 +00:00
To see where this installation root is check out `man cargo-install`.
2016-10-03 18:44:06 +00:00
To change the $PATH in bash:
2016-07-30 10:33:55 +00:00
```bash
$> PATH=$PATH:~/.cargo/bin
$> imag --help
```
2016-07-30 10:33:55 +00:00
To test, simply add `--help` to one of the above commands:
```bash
$> imag counter --help
2016-07-30 10:33:55 +00:00
```
2016-10-07 15:16:45 +00:00
## Staying up-to-date
Despite we have a [official site for imag](http://imag-pim.org), 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"](http://beyermatthias.de/tags/imag.html)
I also post these blog posts
[on reddit](https://www.reddit.com/r/rust/search?q=What%27s+coming+up+in+imag&restrict_sr=on)
and submit them to [this-week-in-rust](https://this-week-in-rust.org/).
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
2016-10-03 18:44:06 +00:00
For detailed information, please read [the documentation](./doc/).
You can either read the Markdown files or compile it to HTML/PDF using
[pandoc](http://pandoc.org).
Developer documentation is also available
[online on github.io](https://matthiasbeyer.github.io/imag/imag_documentation/index.html).
2015-10-30 22:52:43 +00:00
2016-07-30 10:33:55 +00:00
Please note that the documentation is work in progress as well and may be
outdated.
2016-10-03 18:44:06 +00:00
## Please contribute!
2016-10-04 11:49:57 +00:00
We are looking for contributors!
2016-10-03 18:44:06 +00:00
There is always a number of
[complexity/easy tagged issues](https://github.com/matthiasbeyer/imag/issues?q=is%3Aopen+is%3Aissue+label%3Acomplexity%2Feasy)
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](./CONTRIBUTING.md)!
## Contact
2016-08-02 12:22:58 +00:00
Have a look at [our website](http://imag-pim.org) where you can find some
information on how to get in touch and so on.
2016-08-02 12:22:58 +00:00
Feel free to join our new IRC channel at freenode: #imag
or our [mailinglist](http://imag-pim.org/mailinglist/).
## License
2015-11-30 15:30:20 +00:00
We chose to distribute this software under terms of GNU LGPLv2.1.
2015-11-08 16:35:11 +00:00
This decision was made to ensure everyone can write applications which use the
imag core functionality which is distributed with the imag source distribution.
2015-11-08 16:35:11 +00:00