The architecture is made out of modules and interfaces between these modules.
The descriptions below tell what the main functionality of each module is, and
with which other modules it interfaces.
The use cases show how the modules are used.
This should match with the module descriptions here.
The explanation of interfaces is here.
The functionality mentioned here is what will eventually be available.
Not everything will be available in the first release.
The plan shows how and when the modules will
Version control wrapper
Personal version control
Issue tracker wrapper
This is the spider in the web.
At a later stage this module probably has to be split up, since it contains so
- Parse recipes.
- Execute rules in recipes, such as: configure, compile, package,
install, test, distribute, build cross reference, report a problem.
- Handle default rules for many purposes, such as unpacking archives,
compiling, generating dependency files and applying patches.
- Execute external commands and script language snippets in recipes.
- Various ways to recognize changed files (smart signatures, e.g., by
ignoring changes in white space and comments).
- Inspect the system for properties that are used in rules.
- Handle user, project and system preferences related to recipes.
- Handle included recipes, which may be generated automatically.
- Download files (new or updated) with several methods.
- Use lists of alternative sites to download from, with the method used
for downloading (URL or version control system).
- Handle updating a recipe by downloading from the sites specified in the
recipe itself; continue in the updated recipe.
- Handle dependencies on other packages and tools, download or install
them as needed.
- Cache downloaded files.
- Interact with the user about configuration choices; obtain choices from
a configure script; remember choices for a next time.
- Use the package program of the system to install an application and
register it has been installed.
- Support backing up before an install, so that an uninstall is easy to
- Handle targets for different configurations (e.g., debugging, also
called a variant build). Avoid rebuilding everything when the same
configuration was built before.
- Filter (error) messages into a uniform format, so that an editor can
easily parse them.
- Start an editor to handle errors (when the executive was invoked from
the command line).
- Cleanup backed up install files, outdated and scratch files; with a
user command or after a specified timeout.
- Sandbox to limit security riscs.
- Take care of security issues (login to other systems, working as
- Figure out which patches in a list still need to be applied.
This module inspects source files for other files it depends on. For example,
for C code it checks for "#include" lines. The idea is that when the included
file changes, the source file that includes it must be compiled, even though
it didn't change itself.
Related design decisions:
- Generates a recipe that specifies which build rules must be executed
when a file is outdated compared to other files.
- Uses external tools to do the actual work (like "make depend").
- Also works for a configuration script, e.g., to discover a new version
of a library was installed.
8. Format to use for dependency files
15. Interface between Recipe Executive and Dependency Checker
A developer writes a list of items that need to be checked to adjust an
application to the system it will be build for. This module will read the
file and produce a script that will figure out the configuration.
- Autoconf-like system, but portable and easier to use.
- Generates a portable script language instead of Unix shell script.
This actually uses the recipe format.
- The input file is easy to write and edit.
- The input file may contain snippets of the used script language.
- Optionally it inspects source files to find out which configuration
checks need to be done (using the recipe to find the source files).
- Contains many rules that several people need to use.
- NOT simple if-then-else constructs that can be done by recipes.
- Invoked by the "recipe executive" to generate
a Python script from an aap configuration script.
This module builds databases, which it later uses to quickly locate symbols in
- For each language a parser that extracts symbols and context (also
available for use by an editor to locate symbols within one file).
- Uses multiple database files (per directory, per project, for a
library, for the system).
- Writing of a database file.
- Also used for locating documentation (locally or on the internet).
- Reads recipes to lookup what files a project contains and a list of
relevant database files for the project (TODO: using the recipe
executive to parse the recipe?).
- Check for updated files and merge them into an existing database.
- Look up items in the database files (also available as a library, to be
used in other tools, such as an editor).
- Command line tool for looking up symbol locations with grep-like
- Start a viewer, depending on the file type of where a symbol is found
(e.g., a web browser or an ordinary editor.
- NOT: GUI for browsing projects.
Version control wrapper
Uniform wrapper around existing version control systems.
- Display and merge changes from the global project; update to another
- Distribute changes (patches) towards the global project.
- Works with or without a local version control system.
- Global project may be in another VCS than the personal VCS.
- Easy and uniform interface to various version control systems for the
most often used tasks.
- Provide a reference to relevant Issues in the issue tracking
- Take care of security issues.
Personal version control
Limited version control system (VCS) for use by one person.
The difference with traditional VCS is that there are no explicit "checkin" or
"checkout" commands. Every file write automatically creates a new version,
it's like making a backup every time.
- Handle all the changes in files a developer is working on.
- Mark the current set of files as a version.
- Create a patch for the difference between two (marked) versions.
- Retrieve an old version of a file and implicitly create a branch by
- Exchange parts with other developers (peer-to-peer?).
Issue tracker wrapper
Provides a uniform interface for various issue tracker systems.
- Create a new issue, using information passed on from the
"recipe executive" and properties of the local
system to fill in as much of the items as possible.
- Help the user by explaining what he has to do (e.g., by referring to a
web page for the application about reporting problems) and initiating the
actual issue tracker system.
- Change the status of an issue.
- Handle references to patches and versions that fix issues.
- Form a framework for various tools/plugins to work together; defines
the interfaces between these tools/plugins:
- editor - compiler interface (jump to warning/error locations)
- editor - debugger interface
- editor - project browser interface
- editor - cross referencer interface
- editor - viewer interface
- editor - graphical designer interface
- Uses a recipe for project file and preferences. Also knows about
recipes in subdirectories and generated recipes used for depencies and
- Generate recipe from a template; offer the user a choice of
templates for a new project.
- Change simple things in a recipe with the GUI; allow the user to edit
the recipe in a text editor.
- Add files to the project with a dialog (source files, aap configuration
scripts, documentation, etc.).
- Executes recipes through the
"recipe executive"; handle resulting error
messages and start an editor for them.
- Integrated with the
"version control wrapper" and
"personal version control", browsing of
- Browse the project by the symbols used. The results of a search are
displayed in a list. Also used as class browser.
Error messages are displayed in a similar list.
- Run the application in several ways, including for debugging.
Automatically build the application for that way.
Like the GUI IDE, but runs on a console or terminal.
GUI-specific features are missing (everything that involves graphics).
Menus and dialogs are simulated with highlighted text.
- Implements as much of the GUI version as possible.
- Works in DOS console, Linux console, color xterm, etc.
The filetype detection was not originally defined as a separate module, but it
turned out to be needed anyway.
Its purpose is to detect the type of a file from its name or its contents.