# The TaskJuggler Manual

Chris Schläger
Marc Rührschneck
2001, 2002, 2003, 2004, 2005, 2006 Chris Schläger
Version 2.4.1
2.4.1

This document describes TaskJuggler version 2.4.1

TaskJuggler Project Management Gantt Chart Task Resources

## About this document

This document describes TaskJuggler version 2.4.1

The TaskJuggler manual consists of two parts. The first part contains general usage information and a tutorial. The tutorial is highly recommended for all first-time TaskJuggler users. It is a very good introduction to many TaskJuggler concepts and features. The second part is the language reference.

## Introduction

### About TaskJuggler

TaskJuggler is a modern and powerful project management tool. Its new approach to project planning and tracking is far superior to the commonly used Gantt chart editing tools. It has already been successfully used in many projects and scales easily to projects with hundreds of resources and thousands of tasks.

TaskJuggler is an Open Source tool for serious project managers. It covers the complete spectrum of project management tasks from the first idea to the completion of the project. It assists you during project scoping, resource assignment, cost and revenue planning, risk and communication management.

TaskJuggler provides an optimizing scheduler that computes your project time lines and resource assignments based on the project outline and the constrains that you have provided. The built-in resource balancer and consistency checker offload you from having to worry about irrelevant details and ring the alarm if the project gets out of hand. Its flexible "as many details as necessary"-approach allows you to still plan your project as you go, making it also ideal for new management strategies such as Extreme Programming and Agile Project Management.

If you are about to build a skyscraper or just want to put together your colleague's shift plan for the next month, TaskJuggler is the right tool for you. If you just want to draw nice looking Gantt charts to impress your boss or your investors, TaskJuggler might not be right for you. It takes some effort to master its power, but it will become a companion you don't want to miss anymore.

### Features and Highlights

- Manages tasks, resources and costs in one package

- Automatic resource leveling, tasks conflict resolutions, and task filtering

- Comprehensive and flexible views and reports so you can find the information you need when you need it

- Built-in templates to get you started (you can also save your own schedules as templates for future use)

- Project tracking and status reporting

- Graphical User Interface to conveniently edit your projects, view and generate Gamtt charts and reports

- Unlimited number of scenarios (baselines) of same project for what-if analysis

- CSV data export for exchange with Office Suites

- Risk analysis

- Project breakdown and management team support

- Flexible working hours and vacation handling

- Support for shift working

- Multiple timezone support

- Tasks may have initial costs, finishing costs

- Resources may have running costs

- Support for profit/loss analysis

- HTML and XML report generation

- Powerful project description syntax with macro support

- Support for central resource allocation database

### TaskJuggler on the Web

The official TaskJuggler web site can be found at http://www.taskjuggler.org.

Since the developers are mostly busy project managers themselves, we have created a forum for users to help each other.

&ChangeLog;

### How to Contribute

#### Why contribute?

TaskJuggler is an Open Source Project. It was developed by volunteers mostly in their spare time. Made available under the GNU General Public license and similar licenses, TaskJuggler can be shared and used free of charge by anybody who respects the license conditions. Does that mean you can use it without worrying about anything? Clearly not! Though users have no legal obligation to contribute, you should feel a moral obligation to support Open Source in whatever way you can. This can range from helping out other users with their first Linux installation to actively contributing to the TaskJuggler Project, not just as a programmer. The following section describes, how you can contribute to any of the components that are part of the TaskJuggler software releases.

#### Preparing a contribution

All TaskJuggler development is coordinated using the git revision control system. All changes must be submitted using git so that we can track the authorship of each submission. To contribute you need to have at least git version 1.5.0 installed. As a first step, you need to checkout the latest version of the TaskJuggler. This will create a directory called `taskjuggler` in your current directory. It not only contains the latest sources, but also the full revision history of the code. It is your local copy of the TaskJuggler source repository.

    git clone http://www.taskjuggler.org/git-repos/taskjuggler.git

If you have never used git before, you need to configure it first. You need to set your name and email address. This information will be present in all patches that you submit.

    git config --global user.name "Your Name"
    git config --global user.email "firstname.lastname@domain.org"

You then need to configure and install the TaskJuggler version. Make sure, you have removed all other instances of TaskJuggler removed from you system before doing so. It is a common mistake to have an old version of the TaskJuggler library used by a newer version of the executables.

    cd taskjuggler
    make -f Makefile.cvs
    ./configure # Put your options here (see ./configure --help
    for details)
    make
    # Run as root
    make install

Do not use the development snapshots and send your patches as plain diff files. After having switched to git, we no longer accept such patches.

Next you need to find the files where you want to make your modifications. Sometimes files will be generated from other files. Do not change those generated files. Your changes will be overwritten the next time you call the make utility. To identify those files, some familiarity with make and other Linux tools are helpful. Whenever there is a file with the same base name and the extension `.in` in the same directory, then the file is generated from the `.in`-file. You need to modify the `.in`-file, not the one with just the base name. Another indicator is the fact that the file is not part of the repository. With few exceptions the repository does not contain any generated files.

#### Creating a Patch

When you are done with your changes, it's a good idea to test them. In the `taskjuggler` directory run the following commands.

    make
    # Run as root
    make install

If there are no errors, you can check or test the result. If everything works fine, you can lock at your changes again.

    git diff

The git-diff utility performs a line-by-line comparison of the files against the latest version in you local repository. Try to only make changes that have an impact on the generated files. Do not change indentation or line wrapping of paragraphs unless absolutely necessary. These kinds of changes increase the size of diff files and make it much harder to evaluate the patches. When making changes to the program code, please use exactly the same coding style. If your contribution is large enough to justify a copyright claim, please indicate what copyright you claim in the patch. For modifications to existing files, we will assume that your contribution falls under the same license as the modified file. All new files will need to contain a license declaration, preferably GPL version 2. In any case, the license must be an OSI accepted license and be compatible with the rest of the project.

Review all changes carefully. In case you have created new source files, you need to register them with your repository.

    git add FILENAME

If you think you are done, you can commit your changes to your local repository.

    git commit -a

Whenever you have made a certain change or added a certain feature, you should commit your changes to your local repository. This keeps patches small and makes reviewing them easier. The easier your patches can be reviewed, the more likely they will get in.

The final step to submit your changes is to package them up and sign them. It is always a good idea to check for upstream changes again.

    git pull

This makes sure you are really committing your patches against the latest version of the source code. In case there were upstream changes, you need to merge them first. Usually git does this automatically. Refer to the git manual for details on resolving conflicts during merges. Now you can create the patch or patch-set.

    git format-patch -s origin

This will generate a number of files starting with 5-digit file names. You then need to attach these files to a posting in the TaskJuggler Developer Forum.

#### Contributing Translations

Another possible area of contribution are translations of TaskJuggler into languages other than US-English. Our development process is in principle prepared for translations, but the first translation will definitely be a bit difficult to do. TaskJuggler has several hundred messages and more than two hundred pages of documentation. Any translation is a significant effort and an ongoing commitment. TaskJuggler is still actively developed and this will require the translations to be updated as well. Please understand that we do not want to ship partial or outdated translations to our users, so please ensure you or a group of people are willing to maintain the translations.

#### Some final words to Contributors

We do welcome all contributions, but please understand that we reserve the right to reject any contribution that does not follow the above guidelines or otherwise conflicts with the goals of the TaskJuggler team. It is a good idea to contact the team prior to making any larger efforts.

## Installation

### Obtaining TaskJuggler

TaskJuggler may be obtained from the following web site:

http://www.taskjuggler.org

### The TaskJuggler Components

TaskJuggler consists of several modular components that you may or may not need. TaskJuggler also uses some additional tools. We have avoided to re-invent the wheel wherever possible. We tried to keep the dependency list reasonably small, but it nevertheless can be challenging for an inexperienced user to build and install TaskJuggler from source code. Most users are probably better served by using binary packages from their distributor. Almost every mainstream distribution has TaskJuggler included in recent versions of their product. If not, you might like to contact them to inform them that they are missing an essential package.

This version of TaskJuggler was built and tested on SuSE Linux 10.0 and 10.1 on various hardware platforms.

#### The Graphical User Interfaces

With version 2.2 came a new graphical front-end. It's an integrated project management environment.

The front-end is called `TaskJugglerUI`. Don't confuse this with `taskjuggler`, which is the commandline version. When you want to start TaskJugglerUI from a shell, you need to type it with the capital letters.

The graphical front-end makes use of the libraries of the K Desktop Environment. We recommend to use at least version 3.4. Earlier versions will probably work as well, but we have not tested them.

#### The command line tool taskjuggler

To build and run TaskJuggler, you need:

- Qt — The Qt C++ class library version 3.3 or higher

- GNU Compiler Collection — We are currently using GCC 4.0 to develop TaskJuggler. Since we try to write the code platform independent and ANSI standard compliant it should work with most other compilers as well.

The requirements listed are enough to build and use the command line program that translates project descriptions into HTML or XML reports. If you want to build this documentation or use the tools to process the XML files you need to install the additional dependencies. If any of the following dependencies are not matched, the configure script will issue a warning but will not fail.

#### The TaskJuggler Documentation

- DocBook4 — The DocBook system with additional stylesheets and utilities.

- docbook-utils— The jade wrapper scripts from Eric Bischoff.

- OpenJade — The OpenJade system.

- JadeTeX — If you want to build the Postscript version of the documentation you need the JadeTeX macro package for teTeX.

- XSLT Processor — like xsltproc from the libxslt package.

- Meinproc — the XSLT processor for the KDE Helpcenter. You only need meinproc in case you want to build the GUI. meinproc is part of any KDE distribution.

- dvips — This is usually part of your TeX system like te_latex.

#### Contributed Stuff

Several people have contributed useful tools for TaskJuggler users. These tools can be found in the Contrib directory of the source code package. Please refer to the included README files for installation information.

### Compilation and Installation

Before compiling TaskJuggler you need to set the `QTDIR` environment variable to the base directory of your Qt version. This is normally `/usr/lib64/qt3` or `/usr/lib/qt3`.

To compile and install TaskJuggler on your system, type the following in the base directory of the TaskJuggler distribution:

    % ./configure
    % make
    % make install

Since TaskJuggler uses `autoconf`, you should have no trouble compiling it. TaskJuggler has some weak or non-mandatory dependencies. If any of these are not satisfied, a warning is issued. In case a mandatory dependency is not found, an error is displayed and the configuration program stops. If you have problems, please report them to the TaskJuggler user forum at http://www.taskjuggler.org/FUDforum2 in English. Someone there can help you out.

In case you want to build TaskJuggler without the graphical front-end, you can disable it during the configuration process:

    % ./configure --with-kde-support=no --prefix=/usr/local
    % make
    % make install

## Usage

### Basics

TaskJuggler uses one or more text files to describe a project. The main project should be placed in a file with the `.tjp` extension. This main project may contain several sub-projects. Such sub-projects should be placed in files with the `.tji` extension. These sub-projects are included in the main project during compile time.

When TaskJuggler is used with other tools, the project description or the reports may also be in XML format. The recommended extension for such files is `.tjx`.

### General Usage

To use the graphical front-end simply start it from the menu. Depending on your Linux Distribution you will usually find it under Office/Project Management or a similar entry. To start it from a shell type

    % TaskJugglerUI

The commandline version of TaskJuggler works like a compiler. You provide the source files, it computes the contents and creates the output files.

Let's say you have a project file called `AcSo.tjp`. It contains the tasks of your project and their dependencies. To schedule the project and create report files you have to ask TaskJuggler to process it.

    % taskjuggler AcSo.tjp

TaskJuggler will try to schedule all tasks with the specified conditions and generate the reports that were requested with the htmltaskreport, htmlresourcereport or other report properties in the input file.

In contrast to the commandline version the GUI does not generate all reports directly after scheduling. Only the report that was visible previously will be generated. All other reports including export reports will be generated when viewed or requested by the right mouse button menu.

### The Command Line Options

- --help
- Print all command line options with a short description.
- --version
- Print the version and copyright info.
- -v
- Same as '--version'.
- -s
- Stop TaskJuggler's run after syntax check. This option is for testing and debugging purposes only.
- -M
- Output fragment of a Makefile that lists the dependencies of the passed TaskJuggler files.
- --makefile <file>
- Similar to '-M' but write the dependency information into the specified file.
- --maxerrors N
- Specifies the number of errors after which TaskJuggler stops checking the input files. If N is 0 all errors are displayed.
- --nodepcheck
- Do not check for dependency loops. The loop detector uses an algorithm that needs exponentially more time the bigger the dependency network gets. So for large projects it can be desirable to skip the dependency loop detection. This does not affect the task scheduling but can lead to error messages that are difficult to associate with the dependency specification that is wrong.
- --debug N
- Print debug output; N must be between 0 and 4, the higher N the more output is printed. This option is for testing and debugging purposes only.
- --dbmode N
- Limit debug output to certain modules of the code; N is a bit mask. Each set bit activates output of a certain module. Currently the following modules are supported: Project File Reader (1), Project Scheduler (2), Task Scheduler (4), Resource Scheduler (8), Expression Tree Evaluator (16). This option is for testing and debugging purposes only.
- --warnerror
- Warnings are treated as errors.

Calling TaskJuggler with . as input filename will cause reading from stdin. To redirect output to stdout you can specify -- as filename for reports. This feature can for example be used to generate dynamic HTML pages from CGI scripts.

### Reporting Bugs and Sending Feedback

All official releases of TaskJuggler are meant to be stable releases unless explicitly noted differently. But our test suite is still very small and some features are not tested automatically very well. So it's very likely that your current version of TaskJuggler contains some bugs. If you find a bug, please follow this procedure:

- Read this manual to make sure that it is actually a bug and not a feature.

- Check the TaskJuggler web page. Possibly the bug was already found and a patch or workaround exists.

- Try to create a test project that is as small as possible but still reproduces the bug.

- Send the test project and a detailed description of the problem to the developer forum at http://www.taskjuggler.org/FUDforum2.

&FirstProject; &UsageGuide; &SyntaxReference; &PropertyReference;

## The Example: Accounting Software

&Example;

## Migrating from TaskJuggler 1.x to 2.x

### Achieving compatibility

Are you also frustrated by tools that can't read the data of their earlier incarnations? After all, those files contain your valuable data and the first impression of the wonderful new version is its failure to read your old files. With TaskJuggler we like to spare you such situations as much as possible. But TaskJuggler 1.x was written to solve the problems that we encountered. By releasing it to the general public we learned that TaskJuggler is also very useful to many other people. Some contacted us to tell us that it would be even more useful to them, if TaskJuggler could have this or that new feature. In many cases we added these new features but we learned more and more that some parts of the original TaskJuggler design were not flexible enough to support some new features. For TaskJuggler 2.x we decided to change TaskJuggler to a more flexible design even if this meant that some syntax constructs would no longer be supported.

As TaskJuggler uses plain text file as its main data format, you will always be able to read in your old files. But in some cases, you need to change certain syntax constructs to the new syntax. When TaskJuggler processes a file with deprecated syntax it will generate an error message. This usually contains a hint, how the statement should look like in the new syntax. The following sections discuss the conceptual changes and what statements need to be changed.

#### Syntax changes

TaskJugger 1.x could only handle two scenarios with the fixed name `plan` and `actual`. TaskJuggler 2.0 can now handle any number of scenarios. Scenario specific task attributes have to be prefixed with the scenario ID followed by a colon. The attributes starting with 'plan' or 'actual' have been deprecated.

HTML reports are now a lot more flexible. New CSS elements are used and the table elements are customizable now. Old stylesheets will no longer work, since the attribute names have changed. An HTML report contains CSS attribute class specifications if you provide a custom stylesheet definition with rawstylesheet.

The scenario name is no longer displayed by default if more than one scenario is included in a report. A column `scenario` must be explicitly added if the scenario name should be reported for each line. The attributes 'showactual' and 'hideplan' have been deprecated. The scenarios attribute now controls which scenarios should be shown.

The format of numbers and currency values can now be specified with numberformat and currencyformat. The old keyword currencydigits has been deprecated.

workinghours and currency are no longer global properties. They are now optional attributes of the project property.

Container tasks in export reports no longer have fixed start and end dates, if they have their subtasks exported as well.

The functions for Logical Expressions are now using capital letters to improve their readability. The all lowercase versions are still supported, but the recommended versions are now the ones with intermixed uppercase letters. `isTaskOfProject` was added as new query function.

Support for a new XML format has been added. The old format is still supported. TaskJuggler can read both old and new format XML files but will use the new XML format for output.

#### Scheduler changes

Length and duration tasks with resource allocations are no longer trimmed to the first and last resource allocation. This can lead to different schedules.

'length' based tasks now use the global working hours and global vacation settings as a criteria of what is a working day. The tasks now always end during working hours and not at midnight.

The maximum allocation of a resource for a task is no longer limited by default. maxeffort now defaults to 0 (unlimited) instead of 1.0 (8 hours per day). To have the same behaviour as in TaskJuggler 1.x, you need to specify `maxeffort 1.0` before any resource definition. This change was made since many users were confused when after increasing the daily working hours resources were still only allocated 8 hours per day.

## Questions and Answers

### General Questions

Q: Why does taskjuggler use Qt when it's not an X11 application?

A: Qt is a very powerful library that is much more than just a widget library. TaskJuggler uses Qt for all kinds of internal data types like lists and arrays. It also uses the Unicode functions, the SQL database interface and the XML support of Qt.

### Compiling and installation

Q: Can TaskJuggler be compiled and used on Windows?

A: Probably yes, but we have never tried it. It should compile but may require some minor tweaks of the source. You should have good knowledge of C++ and Qt when you try this. Please let us know if you were successful.

### Usage

Nothing here yet.

## Copyright

TaskJuggler Copyright 2001, 2002, 2003, 2004, 2005 Chris Schläger <cs@suse.de>

This program is free software. You can redistribute it and modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

## Trademarks

Linux is a registered trademark of Linus Torvalds.

KDE and the K Desktop environment are registered trademarks of KDE e. V.

TaskJuggler is a trademark of Chris Schläer.

UNIX is a registered trademark and The Open Group are trademarks of The Open Group in the US and other countries.