User Documentation

A Brief Intro

DevAssistant - start developing with ease

DevAssistant (http://devassistant.org) can help you with creating and setting up basic projects in various languages, installing dependencies, setting up environment etc.

It is based on idea of per-{language/framework/...} “assistants” (plugins) with hierarchical structure.

Note: prior to version 0.10.0, DevAssistant has been shipped with a default set of assistants that only worked on Fedora. We decided to drop this default set and create DAPI, DevAssistant Package Index, https://dapi.devassistant.org/ - an upstream PyPI/Rubygems-like repository of packaged assistants. DAPI’s main aim is to create a community around DevAssistant and provide various assistants with good support for various platforms - a task that DevAssistant core team alone is not able to achieve for a large set of assistants.

This all means that if you get DevAssistant from upstream repo or from PyPI, you will have no assistants installed by default. To get assistants, search DAPI through web browser or run da pkg search <term> and da pkg install <assistant package> . This will install one or more DAPs (DevAssistant Packages) with the desired assistants.

If you want to create your own assistants and upload them to DAPI, see http://docs.devassistant.org/en/latest/developer_documentation/create_assistant.html and http://docs.devassistant.org/en/latest/developer_documentation/create_assistant/packaging_and_distributing.html.

There are four main modes of DevAssistant execution. Explanations are provided to better illustrate what each mode is supposed to do:

create
Create new projects - scaffold source code, install dependencies, initialize SCM repos ...
tweak
Work with existing projects - add source files, import to IDEs, push to GitHub, ...
prepare
Prepare environment for working with existing upstream projects - install dependencies, set up services, ...
extras
Tasks not related to a specific project, e.g. enabling services, setting up IDEs, ...

These are some examples of what you can do:

# search for assistants that have "Django" in their description
$ da pkg search django
python - Python assistants (library, Django, Flask, GTK3)

# install the found "python" DAP, assuming it supports your OS/distro
$ da pkg install python

# find out if the installed package has documentation
$ da doc python
INFO: DAP "python" has these docs:
...
INFO: usage.txt
...
# show help
$ da doc python usage.txt

# if the documentation doesn't say it specifically, find out if there is a "create"
#  assistant in the installed "python" DAP
$ da create -h
...
{..., python, ...}
...

# there is, so let's find out if it has any subassistants
$ da create python -h
...
{..., django, ...}
...

# we found out that there is "django" subassistant, let's find out how to use it
$ da create python django -h
<help text with commandline options>

# help text tells us that django assistant doesn't have subassistants and is runnable, let's do it
$ da create python django -n ~/myproject # sets up Django project named "myproject" inside your home dir

# using the same approach with "pkg search", "pkg install" and "da tweak -h",
#  we find, install and read help for "tweak" assistant that imports projects to eclipse
$ da tweak eclipse -p ~/myproject # run in project dir or use -p to specify path

# using the same approach, we find, install and read help for assistant
#  that tries to prepare environment for a custom upstream project, possibly utilizing
#  its ".devassistant" file
$ da prepare custom -u scm_url -p directory_to_save_to

# sometimes, DevAssistant can really do a very special thing for you ...
$ da extras make-coffee

Should you have some questions, feel free to ask us at Freenode channel #devassistant or on our mailing list (https://lists.fedoraproject.org/mailman/listinfo/devassistant). You can also join our G+ community (https://plus.google.com/u/0/communities/112692240128429771916) or follow us on Twitter (https://twitter.com/dev_assistant).

Installation

If you can, use the packaged version

To install DevAssistant on your machine, there is usually more than one way. If you use a Linux distribution where DevAssistant is already packaged, we strongly suggest you use the packaged version. Doing so can save you quite a few headaches with configuration and making sure everything works. This applies especially to Fedora, where it is us, the DevAssistant development team, who cares about the packaging.

Install from PyPI

If you don’t wan’t to use the packaged version or there isn’t one for your OS in the first place, you can install DevAssistant from the Python Package Index via the pip tool. In a large majority of distributions, pip is packaged in the system repositories.

However, even though pip makes sure the specified dependencies are met, it is simply not enough to allow you to run DevAssistant to the fullest extent. To achieve that, you’ll need to do some manual steps:

  • Make sure GTK+ version 3 is installed (the package’s name will probably be something like gtk3)
  • Make sure the askpass dialog for OpenSSH is installed (in Fedora, the package is called openssh-askpass).
  • Make sure git is installed.
  • Make sure setuptools are installed for the version of Python you intend to use for running DevAssistant
  • If you want to use the Docker functionality, you’ll need Docker installed, and a Python client for Docker (on PyPI, it’s called docker-py). These may not be available on some architectures.
  • If you want to use DevAssistant with an RPM-based distribution, you’ll need either YUM or DNF installed. DNF runs only on Python 3, so you will have to run DevAssistant under Python 3 as well. Furthermore, DNF’s bindings are most likely in a separate package, in Fedora packaged as python3-dnf.

Run from source

DevAssistant is perfectly runnable from source as well. For this, the same applies as for installing from PyPI, plus you need to install the contents of requirements.txt (and requirements-py2.txt if you want to run DevAssistant under Python 2) in the root folder of the tarball. To do that, you can run the following command(s) in the unpacked DevAssistant folder:

pip install --user -r requirements.txt
pip install --user -r requirements-py2.txt # Only on Python 2

P. S. We suggest you add the --user flag so that the packages are installed in the ~/.local directory in your home instead of system-wide. If you perform system-wide pip installations, you risk breaking packages installed by the system.

So What is an Assistant?

In short, Assistant is a recipe for creating/tweaking a project or setting up the environment in a certain way. DevAssistant is in fact just a core that “runs” Assistants according to certain rules.

Each Assistant specifies a way to achieve a single task, e.g. create a new project in framework X of language Y.

If you want to know more about how this all works, consult Create Your Own Assistant.

Assistant Roles

There are four assistant roles:

creator (create or crt on command line)
creates new projects
tweak (tweak or twk on command line)
works with existing projects
preparer (prepare or prep on command line)
prepares environment for development of upstream projects
extras (extras or extra on command line)
performs arbitrary tasks not related to a specific project

The main purpose of having roles is separating different types of tasks. It would be confusing to have e.g. python django assistant (that creates new project) side-by-side with eclipse assistant (that registers existing project into Eclipse).

You can learn about how to invoke the respective roles below in Creating New Projects, Working with Existing Projects, Preparing Environments and Extras.

Using Commandline Interface

Getting Assistants

By default, DevAssistant comes with no Assistants pre-installed. If you want to install some, you can get them from DAPI, DevAssistant Package Index, https://dapi.devassistant.org/.

You can do that from DevAssistant itself. If you want Flask related Assistants, you can run:

$ da pkg search flask
python - Python assistants (library, Django, Flask, GTK3)

da is the short form of devassistant. You can use either of them, but da is preferred.

pkg is an action for manipulating DAPs - DevAssistant packages. It contains several sub-actions, such as search used here. To get more info about this python DAP, you can use info:

$ da pkg info python
python-0.10.1
=============

Python assistants (library, Django, Flask, GTK3)

Set of crt assistants for Python. Contains assistants that let you
kickstart new Django or Flask web application, pure Python library or GTK3 app.
Supports both Python 2 and 3.

...

The following assistants are contained in this DAP:
 * crt/python/flask
 * crt/python/django
 * crt/python/lib
 * crt/python/gtk3
 * crt/python

If you are satisfied, use install to actually get it:

$ da pkg install python
INFO: Installing DAP python ...
INFO: Successfully installed DAPs python common_args vim eclipse github

As you can see, the command did not only install the python DAP, but several others. That’s because python depends on those and cannot work properly without them.

If you want to remove some DAP, use either uninstall or remove (they do the same):

$ da pkg remove python
INFO: Uninstalling DAP python ...
DAP python and the following files and directories will be removed:
    ~/.devassistant/meta/python.yaml
    ~/.devassistant/assistants/crt/python.yaml
    ~/.devassistant/assistants/crt/python
    ~/.devassistant/files/crt/python
    ~/.devassistant/icons/crt/python.svg
    ~/.devassistant/snippets/python.yaml
    ~/.devassistant/doc/python
Is that OK? [y/N] y
INFO: DAPs python successfully uninstalled

Once in a while, you can update your DAPs. Either all of them like this:

$  da pkg update
INFO: Updating all DAP packages ...
INFO: Updating DAP git ...
INFO: DAP git successfully updated.
INFO: Updating DAP common_args ...
INFO: DAP common_args is already up to date.
INFO: Updating DAP eclipse ...
INFO: DAP eclipse is already up to date.
INFO: Updating DAP vim ...
INFO: DAP vim successfully updated.
INFO: Updating DAP github ...
INFO: DAP github is already up to date.
INFO: Updating DAP tito ...
INFO: DAP tito successfully updated.

Or if you want to update just some packages, name them:

$  da pkg update git tito
INFO: Updating DAP git ...
INFO: DAP git successfully updated.
INFO: Updating DAP tito ...
INFO: DAP tito successfully updated.

Creating New Projects

DevAssistant can help you create your projects with one line in a terminal. For example:

$ da create python django -n foo -e -g

What this line does precisely depends on the author of the Assistant. You can always display help by using da create python django -h. Running the above command line may do something like this:

  • Install Django and all needed dependencies.
  • Create a Django project named foo in the current working directory.
  • Make any necessary adjustments so that you can run the project and start developing right away.
  • The -e switch will make DevAssistant register the newly created projects into Eclipse. This will also cause installation of Eclipse and PyDev, unless already installed.
  • The -g switch will make DevAssistant register the project on Github and push sources there.

Working with Existing Projects

DevAssistant allows you to work with previously created projects. You can do this by using da tweak, as opposed to da create for creating:

$ da tweak eclipse

As noted above, what an Assistant does depends on its author. In this case, it seems that the Assistant will import an existing project into Eclipse, possibly installing missing dependencies - to find out if this assumption is correct, run da tweak eclipse -h and read the help.

Preparing Environments

DevAssistant can set up the environment and install dependencies for development of an already existing project located in a remote SCM (e.g. Github). There is, for example, the so-called custom prepare assistant, that is supposed to prepare environments for arbitrary upstream projects. This means that it will checkout the source code from the given git repo and if there is a .devassistant file in the repo, it will install dependencies and prepare environment according to it:

$ da prepare custom -u scm_url

Warning: The custom Assistant executes custom pieces of code from a .devassistant file, so use this only for projects whose upstreams you trust.

We hope that existance of DAPI will attract people from various upstreams to create prepare Assistants for their specific projects, so that people could do something like:

$ da prepare openstack

To get development environment prepared for development of OpenStack, etc...

Extras

The last piece of functionality is performing arbitrary tasks that are not related to a specific project, e.g.:

$ da extras make-coffee

Custom Actions

There are also some custom actions besides pkg, create, tweak, prepare and extras.

  • doc - Displays documentation for a given DAP. Uses less as pager, if available:

    # finds out if "python" DAP has documentation, lists documents if yes
$ da doc python
...
INFO: LICENSE
INFO: somedoc.txt
INFO: docsubdir/someotherdoc.txt
...

# displays specific document for "python" DAP
$ da doc python docsubdir/someotherdoc.txt

  • help- Displays help :)

  • version- Displays current DevAssistant version.

Using the GUI

The DevAssistant GUI provides the full functionality of Commandline Interface through a Gtk based application.

The GUI provides all Assistants of the same type (creating, tweaking, preparing and extras) in one tab to keep things organized.

The GUI workflow is dead simple:

  • Choose the Assistant that you want to use, click it and possibly choose a proper subassistant (e.g. django for python).
  • The GUI displays a window where you can modify some settings and choose from various Assistant-specific options.
  • Click the “Run” button and then just watch as DevAssistant sets up your environment. If your input is needed (such as confirming dependencies to install), DevAssistant will ask you, so don’t go get your coffee just yet.
  • After all is done, get your coffee and enjoy.

Where are the Assistants located?

You may wonder where DAPs are installed. The short answer is ~/.devassistant. However, the long answer is a little bit more complicated.

There are two variable defined in DevAssistant: DEVASSISTANT_HOME and DEVASSISTANT_PATH. Be default, DEVASSISTANT_HOME is set to ~/.devassistant and DEVASSISTANT_PATH contains the following:

  • ~/.devassistant
  • /usr/local/share/devassistant
  • /usr/share/devassistant

DAPs installed from DAPI can be found in DEVASSISTANT_HOME, however, you can run Assistants from all the locations present in DEVASSISTANT_PATH. If the Assistant with the same name is present in more of them, locations on the beginning of the list have bigger priority.

Sometimes the values of DEVASSISTANT_HOME and DEVASSISTANT_PATH are different. For example when installing DAPs as root, ~/.devassistant is no longer there and /usr/local/share/devassistant is used as DEVASSISTANT_HOME instead. So all the users can use Assistants installed by root. You can also redefine the values entirely by using environment variables. The following example will install DAP python to .bah:

$ DEVASSISTANT_HOME=.bah da pkg install python

However, be advised that you cannot use the python Assistants installed this way if you don’t specify the DEVASSISTANT_HOME variable when running DevAssistant again.

Manipulating DEVASSISTANT_PATH is very similar, but directories defined in that variable are used in addition to the default ones. If you want to use only the directories in DEVASSISTANT_PATH, define the variable DEVASSISTANT_NO_DEFAULT_PATH. You must then define DEVASSISTANT_HOME too, because its default value is unset in the process.

Also note that with DEVASSISTANT_NO_DEFAULT_PATH, the DAPs are installed into the first directory from DEVASSISTANT_PATH, not to DEVASSISTANT_HOME.

The pkg command line action works with multiple directories.

  • running install always installs to DEVASSISTANT_HOME. However, the installation will not take place if a package of the same name is present in some location specified in DEVASSISTANT_PATH - to override this behavior, use the --reinstall option.
  • remove/uninstall only removes DAPs from DEVASSISTANT_HOME unless you use the --all-paths option. If you want to remove packages from directories where you don’t have write access, perform the action as root.
  • update updates DAPs in DEVASSISTANT_HOME. It may happen that the transaction requires packages in other locations to be updated too. In that case, those packages will be left untouched, and newer versions will be installed in DEVASSISTANT_HOME. You may override this behavior by using the --all-paths option, but you may need to perform that action as root if you don’t have write access in all the locations.

Note that /usr/share/devassistant is protected from the --all-paths option because it’s supposed to be managed by your distribution packaging system. If you want to disable this protection, just add /usr/share/devassistant to the DEVASSISTANT_PATH environment variable.