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
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:
~/dev/ReDIF-perl
~/dev/AMF-perl
~/dev/RePEc-Index
~/dev/acis
Each project contains a separate source tree, managed with Darcs revision control system.
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.
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.
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.
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.
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.
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
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.
Generated: Fri Jun 11 07:15:03 2010
ACIS project, acis@openlib.org