* User's Guide

*** Initializing tooling to an existing project

To initialize ~jubeo~ metaproject toolign to an existing project
simply run this command:

#+BEGIN_SRC bash
PROJECT="$HOME/scratch/test_proj"
mkdir -p $PROJECT

jubeo init $PROJECT
#+END_SRC

This will use the bare-bones default tooling in the ~jubeo~ source
tree, but if you want to initialize from a specific upstream repo you
can do that as well:

#+BEGIN_SRC bash
jubeo init --upstream https://github.com/salotz/jubeo-pyproject.git $PROJECT
#+END_SRC

Now you should see a ~.jubeo~ project specific configuration directory
as well as a directory called ~tasks~. The ~tasks~ directory is named
as such because the default metaproject tooling uses the python
library ~invoke~ to generate project specific routines. All the
dependencies for the specific ~jubeo~ upstream should be given in the
~.jubeo~ folder as the ~requirements.in~ (abstract non-pinned; YMMV)
and ~requirements.txt~ (pinned versions more likely to work). If you
don't already have them installed go ahead and run:

#+BEGIN_SRC bash
pip install -r requirements.txt
#+END_SRC

In whichever environment you see fit. Depending on the ~jubeo~ taskset
there will be tools for managing project specific virtual environments
but this necessary "bootstrapping" step is currently necessary.

You should have installed at least one dummy target to show how to
execute targets via the default ~invoke~ configuration:

#+BEGIN_SRC bash
cd $HOME/scratch/test_proj
inv custom.hello
#+END_SRC

You can see all the available targets with ~inv -l~.

The targets come in modules which are separated by '.' just like in
python.

*** Updating Your Tooling

The default tooling is intentionally bare-bones because ~jubeo~ is
agnostic to the type of project. Your can update metaproject tooling
by running:

#+BEGIN_SRC bash
jubeo update $HOME/scratch/test_proj
#+END_SRC

This will read the ~.jubeo/jubeo.toml~ configuration file and and grab
the latest tasksets from the ~upstream_url~ which can either be on the
file system or a git repo. You can switch *upstream* sources whenever
by customizing this path.

You can work with just the targets the upstream taskset gives you or
you can add your own project-local targets in the
~$PROJECT/tasks/plugins~ folder. To start there is an example of how
to add a module called ~custom.py~ where the ~custom.hello~ target
came from.

This plugins directory (and the ~tasks/config.py~ file) will never be
altered when ~jubeo~ updates, whereas all of the other files are free
game to be completely altered. So if you want to keep a project
specific target put it in the plugins!


*** Initializing a jubeo project from scratch

Due to the nature of the platform ~jubeo~ was designed for
(i.e. unix-like systems) most behavior is dependent upon a very
particular file-hierarchy structure. One of the major motivations for
building ~jubeo~ was in part to add a layer of indirection between the
project developer/maintainer and all of these finicky and banal
details and focus more on policy and strategy by providing semantic
targets to execute that "Just Work" 80% of the time.

Because of this adopting any new project tooling can be a bit onerous
as you may need to change the project structure around significantly
which can break a lot of things in mysterious and difficult to fix
ways.

For new projects however this isn't as much of a concern and the major
problem is instead manually creating the file-hierarchy structure by
hand. Luckily tools for making this easier exist such as the
[[https://github.com/cookiecutter][cookiecutter]] which we highly suggest using and all of our ~jubeo~
based projects likely come with ~cookiecutter~ templates.




