ACIS Source Code Guide

Table of contents

   Separate components
   Darcs
   Working on a local working copy of a project
   Syncing your local changes with the central repository
   Manifest file
   Basic code editing procedure with Darcs
   Releasing a packaged version
   Building an ACIS package

Separate components

ACIS is not a monolithic program. It is a large collection of modules, scripts, configuration files and templates. And there are several components which are closely related to ACIS and are required to use it. But these components may be used without ACIS, completely independently. Therefore their source code is managed and packaged separately.

The central repository for ACIS is the account aacis@acis.openlib.org. There, we have four directories, which correspond to four projects:

Each project contains a separate source tree, managed with Darcs revision control system.

Darcs

Darcs is an easy-to-use system. It currently lacks some nice-to-have features, if compared to SVN or CVS. It's core advantage is that it supports a purely distributed development.

These component projects and main ACIS source code may be developed right in aacis@acis.openlib.org. But it is better to open your own aacis account on your machine, let us refer to the as mybox here. After a change is done, you need to submit it to the repository. The repository is where the source code revisions are stored. This lives on the account aacis at the host acis.openlib.org.

You will have to study the userguide of Darcs, http://darcs.net/ but you don't have to do it now.

Working on a local working copy of a project

First install Darcs on your machine. Set up your local environment DARCS_EMAIL to your email address. Set the environment DARCS_DONT_ESCAPE_8BIT to 1. Then get a local copy of a project project.

aacis@mybox:~ darcs get --set-scripts-executable aacis@acis.openlib.org:dev/project

This would make you a local directory project in your current directory, where project would be "acis", "ReDIF-perl"and so on. Your local copy of a project's source code is called a working copy.

Syncing your local changes with the central repository

When starting a change:

aacis@mybox:~/dev/project$ darcs pull -a

After doing a change:

aacis@mybox:~/dev/project$ darcs push

or

aacis@mybox:~/dev/project$ darcs push -a

If you create a new module, script or some other file, you may want to do two things, add it to the darcs repository.

aacis@mybox:~/dev/project$ darcs add file_to_add

where file_to_add is the file to add. Then add _file_to_add to the MANIFEST file.

Manifest file

There is a MANIFEST file in each of the project directories. It lists all files to be packaged in a release of the project. A useful command is

aacis@mybox:~/dev/project$ make manifest

See also: MANIFEST.SKIP, google for "MANIFEST.SKIP file" or look it up in the Perl camel book.

Basic code editing procedure with Darcs

For example, let's imagine I had to make a change to the ReDIF-perl project. Here are the first steps of the procedure:

aacis@mybox:~$ cd dev/ReDIF-perl

aacis@mybox:~/dev/ReDIF-perl$ emacs lib/ReDIF/Parser.pm

for example. Then you may want to review the changes that you have made to the code. Darcs would show it to you in a format similar to diff:

aacis@mybox:~/dev/ReDIF-perl$ darcs whatsnew

Then you may want to make sure the change didn't break any tests:

aacis@mybox:~/dev/ReDIF-perl$ make tests

Then let's assume the tests passed fine and you want to submit your change:

aacis@mybox:~/dev/ReDIF-perl$ darcs record -am "an improvement to the parsing algorithm"

The text in quotes is the name of your patch. It should briefly explain the substance of the change, or at least it's character.

Releasing a packaged version

If darcs record worked fine and didn't complain, you may now want to release a new version package to the public. You have to do this at the central repository. Here we use the example of ReDIF-perl. You do the following.

aacis@acis:~/dev/ReDIF-perl$ perl release.pl

That should make a new version number for you and pack a distribution. The version number would be generated automatically, by incrementing the previous one by one. If it was 0.4 the new version would be 0.5; if it was 4.44.4 then the new one would be 4.44.5. The current version number is stored in the Makefile.PL file. See the release.pl file for details.

The release file is generated in the current directory and its full name is printed on the standard output. You may grab it and upload to somewhere for other people to use. For example, ReDIF-perl releases go to http://all.repec.org/ReDIF-perl/.

This is the most basic development scenario for these three auxilary projects. For ACIS itself the darcs part is the same, but it has a separate package building script.

If the release.pl script fails

aacis@acis:~/dev/ReDIF-perl$ MAKEMAKEFILE=1; perl Makefile.PL

aacis@acis:~/dev/ReDIF-perl$ perl release.pl

Building an ACIS package

There are two ways the build an ACIS package. If you just want to package acis as such, you can do

aacis@acis:~/dev/acis$ perl build/dist.pl [version]

where version is the version number. Then you release ReDIF-perl, AMF-perl and RePEc-Index from their separate directories. An ACIS distribution may include these components as well. It will have them in an extra/ subdirectory. Such a full distribution is built using

aacis@acis:~/dev/acis$ perl build/dist.pl -f [version]

where version is the version number.