If your project is more complicated than this, and many are, you may be able to adapt these instructions once you understand what they are trying to achieve. I recommend you read on, and keep notes of where you will have to change things.
These instructions do not assume you are the primary maintainer of this OSS project, you just want “a local branch” for hacking on. These instructions will work just as well for a maintainer, but they do not cover migrating from the present version control tool to Aegis.
The first thing to do is create the project. In order to have good security for your project, the user account which owns the project files needs to be different than the developers. This prevents accidents where the master source could be broken accidentally.
In this example, we will call that user “repos”. Create this user in the usual way for your operating system.
Because this example is going to be talking about two accounts, the repos account, and your usual user account, this example will call your usual user account “user”.
Now, to create the project, use this command:
The “–version –” tells Aegis you don't want it to create a branch hierarchy just yet.user$ su - repos password: repos$ aegis -new-project vgrabbj -version - repos$
The project directory tree will be established in the repos user's home directory. You can put it somewhere else using the -directory command line option, so long as the repos user has write permissions to create that directory.
Next, add you usual user account as a project administrator, using this command:
Remember to replace user with your actual user name.repos$ aegis -new-administrator user -p vgrabbj repos$
The above command established your usual account as a project administrator. All of the remaining steps to create the project may be done from your normal account.
The next step is to add yourself to all of the remaining project roles: developer, reviewer and integrator. You can do this, because you are a project administrator.repos$ exit user$
The next task is to set the project attributes. This is most easily done by using the tkaepa(1) command.user$ ae_p vgrabbj user$ aend user user$ aenrv user user$ aeni user user$
Note: if you aren't using X11, the aepa(1) command will does the same job, and it's what tkaepa(1) invokes, but you will need to read the aepattr(5) man page for the expected input format. For novices, the GUI interface is easier.user$ tkaepa user$
You want to turn on just about everything. For a single person project, turn on
The last step is to create the branches. Assuming vgrabbj is at version 0.9.6, we will create the 0 and 0.9 branches.
Things are nearly ready to go.user$ aegis -new-branch -p vgrabbj 0 user$ aegis -new-branch -p vgrabbj.0 9 user$
The necessary settings and their source file are pre-packaged for you. The following command will download the change set and apply it to the project:
user$ aedist -rec -f http://aegis.sourceforge.net/eg_oss_begin.ae -p vgrabbj -c 900 -vThe change set is applied to the trunk of the project branch tree (the project name doesn't end with .0.9) because files are inherited by sub-branches, and most of these settings will not be changing.
It's worth mentioning that the Aegis project configuration established by this change set consists of five files:
This change will automatically end development, and you need to integrate it. This is because Aegis breaks the commit step into several separate stages, each with its own checks and balances.
The integration step, particularly when it is not being used as a second review stage, is most simply accomplished using the aeintegratq command:
It will take about a minute, and it won't say much if nothing went wrong.user$ aeintegratq vgrabbj user$
At this point, many Aegis commands are available, and you may like to try some if them out.
user$ aedist -rec -f http://aegis.sourceforge.net/eg_oss_aemak.ae -p vgrabbj -c 6 -vThis project uses Automake, Autoconf and Libtool to do all the work. All you have to do is conform to the pretty relaxed expectations in aemakegen(1) of the project directory layout.
Skip this section if you are working with an existing project. Skip down to section “ Template Contents for New Files” if you are starting from scratch.
You need to visit vgrabbj.sourceforge.net and download the latest tarball. This example is based on 0.9.6, but it will not matter very much of the minor version has moved on since this was written.
We created branches 0 and 0.9 before, and now we are going to use them.
This command sets the AEGIS_PROJECT environment variable, so you don't have to keep typing --project=vgrabbj.0.9 all the time.user$ ae_p vgrabbj.0.9 user$
Assuming that the tarball is in the current directory, the following command will unpack it into a change set:
user$ aetar --receive -f vgrabbj-0.9.6.tar.gz -c 6 --exclude-auto-tools --remove-path-prefix=1The --exclude-auto-tools option says to exclude common non-source files (like ./configure) from the tarball if aetar detects the presence of their precursors (like configure.ac). These files will be created by the build system, which will be introduced in the next section. (This option can be abbreviated to -eat.)
...lots of output...
The --remove -path-prefix=1 option says to remove the top-level directory from the filenames in the tarball. It changes with every version, and thus is not helpful when you want to track upstream versions. (This option can be abbreviated to -rpp=1.)
If you read the output of this command (scroll up your terminal window) you can see all of the commands aetar(1) executed for you. Each of the files in the tarball has been created as a source file.
You will also see that it created a private work area for you to do this within, inside you home directory, called a development directory. Every change set gets its own development directory. You can enter this development directory and have a look around using the following command:
That “6” is the change set number. It was specified explicitly on the aetar(1) command line, so that it matches the tarball. If you don't specify a number, the aetar(1) command will use the next available.user$ aecd 6 user$ ls -l user$
There are a number of other Aegis command which now have some content. Try
The “cd” is short for change-details and much faster to type than the long version, though that also works.user$ ael cd user$
You will see that the change description isn't especially informative. You can use the following command to edit the change set's attributes:
Just change the descriptions for now, and resist the urge to kick the tires. You can always create another change set later.user$ tkaeca user$
Note: if you aren't using X11, the aeca(1) command will does the same job, and it's what tkaeca(1) invokes, but you will need to read the aecattr(5) man page for the expected input format. For novices, the GUI interface is easier.
To finish this change set, it's much like the previous one. All of the usual Aegis process will be adhered to (if you consult the User Guide you will see what that means) but it will go by very quickly in this example.
At this point, the most recent upstream version is in your Aegis repository. You can do what you like from now, but the next section gets it to build, so that you can start using some of Aegis more advanced software development process features.user$ aefinish ...lots of output... user$ cd user$ aeintegratq vgrabbj-0.9 user$
There is a second pre-packaged Aegis change set which you can use to have your project be built under Aegis, and enforce such a build policy.
This change set, which you will download very soon, does another thing, as well: it sets the development directory style. Many OSS developers are used to CVS or SVN which make a complete copy of the project when you check out your private work area. And their build systems are based on the assumption that this has happened. Aegis is able to provide this kind of development directory style, however the default is a “view path” style which only has source files in the private work area if they are actually being changed, which can get confusing for new users who are expecting a fully populated source tree.
user$ aedist -rec -f http://aegis.sourceforge.net/eg_oss_build.ae -p vgrabbj.0.9 -c 901 -v -trojanThis command downloads the change set, creates a private work area for it (called a development directory in Aegis speak) and unpacks all the files of the change set into it.
...lots of output...
The -trojan option says to stop once the files are unpacked, and before any builds occur. You can do this for remote changes you are not sure about, but it also gives you a chance to poke about the development directory and see what Aegis has actually done.
The first thing you will want to know is “where have all the source files gone?” Remember the view path thing? The development directory style just downloaded hasn't taken effect yet. The build will take care of that, and we will get to it shortly.user$ aecd 901 user$ ls user$
It is worth taking a look at the files about to be created by this change set. The aegis.conf.d/build file tells Aegis how the project is built. It invokes make(1) with a special makefile which includes the generated Makefile, if it exists, and builds it if it does not (in which case it builds it and starts again). In this way, the build is boot-strapped without altering any of the source files we got from the tarball.
To build, you just need this command:
user$ aebIf you look at the output (scroll the terminal back) you will see that all of the usual and expected things are done to build an OSS project. You will also note that the development directory is now full of source files... this is because the aeb(1) command updated the development directory automatically before running the configured build command. After this change set is integrated, the next time you start a new change set, the development directory will be populated immediately.
...lots of output...
If there are any problems with the build, it is going to be with how the project uses GNU Autoconf and GNU Automake to bootstrap itself. You may need to edit the aegis.supplementary/makefile file to fix the problem. Once the “real” Makefile has been produced, the supplementary file will do nothing.
We will finish this change set the same way as before, using the aefinish(1) command, and then integrate it:
And now the project builds. This would be a good time to read through the worked example in the Aegis User Guide.user$ aefinish ...lots of output... user$ cd user$ aeintegratq vgrabbj-0.9 user$
user$ aedist -rec -f http://aegis.sourceforge.net/eg_oss_templ.ae -p vgrabbj.0.9 -c 902 -vThis change set is finished in the usual way.
This change set also includes a new file template for new tests. You create a new test with the aent(1) command, from within a change set in the being developed state.user$ aefinish user$ cd user$ aeintegratq vgrabbj-0.9 user$
|The beautiful graphics on this web site are by Grégory Delattre.||Return to the Aegis home page.|