User Guide
   Next

Aegis

A Project Change Supervisor

User Guide

Peter Miller



This document describes Aegis version 4.22 and was prepared 11 April 2006.

This document describing the Aegis program, and the Aegis program itself, are

Copyright © 1991-2006 Peter Miller All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

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., 59 Temple Place, Suite 330, Boston, MA 02111, USA.

Dedication


This user guide is dedicated to my wife
           Mary Therese Miller
      for all her love and support
         despite the computers.

         And to my grandmother
          Jean Florence Pelham
                1905 — 1992
          Always in our hearts.

Table of Contents

1. Introduction
1. Year 2000 Status
2. What does aegis do?
3. Why use aegis?
4. How to use this manual
5. GNU GPL
2. How Aegis Works
1. The Model
1.1. The Baseline
1.2. The Change Mechanism
1.3. Change States
1.4. The Software Engineers
1.5. The Change Process
2. Philosophy
2.1. Development
2.2. Post Development
2.3. Minimalism
2.4. Overlap
2.5. Design Goals
3. Security
4. Scalability
5. When (not) to use Aegis
5.1. Building
5.2. Testing
5.3. Reviewing
6. Further Work
6.1. Code Coverage Tool
6.2. Virtual File System
3. The Change Development Cycle
1. The Developer
1.1. Before You Start
1.2. The First Change
1.3. The Second Change
1.4. The Third and Fourth Changes
1.5. Developer Command Summary
2. The Reviewer
2.1. Before You Start
2.2. The First Change
2.3. The Second Change
2.4. Reviewer Command Summary
3. The Integrator
3.1. Before You Start
3.2. The First Change
3.3. The Other Changes
3.4. Integrator Command Summary
3.5. Minimum Integrations
4. The Administrator
4.1. Before You Start
4.2. The First Change
4.3. The Second Change
4.4. The Third Change
4.5. The Fourth Change
4.6. Administrator Command Summary
5. What to do Next
6. Common Questions
6.1. Insulation
6.2. Partial Check-In
6.3. Multiple Active Branches
6.4. Collaboration
4. The History Tool
1. History File Names
2. Interfacing
2.1. history_create_command
2.2. history_get_command
2.3. history_put_command
2.4. history_query_command
2.5. history_content_limitation
2.6. history_tool_trashes_file
2.7. Quoting Filenames
2.8. Templates
3. Using aesvt
3.1. history_create_command
3.2. history_put_command
3.3. history_get_command
3.4. history_query_command
3.5. Templates
3.6. Binary Files
4. Using SCCS
4.1. history_create_command
4.2. history_get_command
4.3. history_put_command
4.4. history_query_command
4.5. Templates
4.6. Binary Files
5. Using RCS
5.1. history_create_command
5.2. history_get_command
5.3. history_put_command
5.4. history_query_command
5.5. merge_command
5.6. Referential Integrity
5.7. Templates
5.8. Binary Files
5.9. history_put_trashes_files
6. Using fhist
6.1. history_create_command
6.2. history_get_command
6.3. history_put_command
6.4. history_query_command
6.5. Templates
6.6. Capabilities
6.7. Binary Files
7. Detecting History File Corruption
7.1. General Method
7.2. Configuration Commands
7.3. An Alternative
7.4. Aegis' Database
5. The Dependency Maintenance Tool
1. Required Features
1.1. View Paths
1.2. Dynamic Include File Dependencies
2. Development Directory Style
2.1. View Path
2.2. Link the Baseline
2.3. Copy All Sources
2.4. Obsolete Features
3. Using Cook
3.1. Invoking Cook
3.2. The Recipe File
3.3. The Recipe for C
3.4. The Recipe for Yacc
3.5. The Recipe for Lex
3.6. Recipes for Documents
3.7. Templates
4. Using Cake
4.1. Invoking Cake
4.2. The Rules File
4.3. The Rule for C
4.4. The Rule for Yacc
4.5. The Rule for Lex
4.6. Rules for Documents
5. Using Make
5.1. Invoking Make
5.2. The Rule File
5.3. The Rule for C
5.4. The Rule for Yacc
5.5. The Rule for Lex
5.6. Rules for Documents
5.7. Other Makes
5.8. Templates
5.9. GNU Make VPATH Patch
5.10. GNU Make's VPATH+
6. Building Executable Scripts
7. GNU Autoconf
7.1. The Sources
7.2. Building
7.3. Testing
7.4. An Optimization
7.5. Signed-off-by
7.6. Importing the Next Upstream Tarball
7.7. Importing the Next Upstream Patch
8. No Build Required
8.1. Why This May Not Be Such A Good Idea
6. The Difference Tools
1. Binary Files
2. Interfacing
2.1. diff_command
2.2. merge_command
3. When No Diff is Required
4. Using diff and merge
4.1. diff_command
4.2. merge_command
5. Using fhist
5.1. diff_command
5.2. merge_command
7. The Project Attributes
1. Description and Access
2. Notification Commands
2.1. Notification by email
2.2. Notification by USENET
3. Exemption Controls
3.1. One Person Projects
3.2. Two Person Projects
3.3. Larger Projects
3.4. RSS Feeds
8. Testing
1. Why Bother?
1.1. Projects for which Aegis' Testing is Most Suitable
1.2. Projects for which Aegis' Testing is Useful
1.3. Projects for which Aegis' Testing is Least Useful
2. Writing Tests
2.1. Contributors
2.2. General Guidelines
2.3. Bourne Shell
2.4. Perl
2.5. Batch Testing
9. Branching
1. How To Use Branching
2. Transition Using aenrls
3. Cross Branch Merge
4. Multiple Branch Development
5. Hierarchy of Projects
5.1. Fundamentals
5.2. Incremental Integration
5.3. Super-Project Branching
5.4. Super-Project Testing
5.5. The Next Cycle
5.6. Bug Fixing
6. Conflict Resolution
6.1. Cross Branch Merge
6.2. Insulation
7. Ending A Branch
10. Tips and Traps
1. Renaming Include Files
2. Symbolic Links
3. User Setup
3.1. The .cshrc or .profile files
3.2. The AEGIS_PATH environment variable
3.3. The .aegisrc file
3.4. The defaulting mechanism
4. The Project Owner
5. USENET Publication Standards
5.1. CHANGES
5.2. MANIFEST
5.3. Makefile
5.4. patchlevel.h
5.5. Building Patch Files
6. Heterogeneous Development
6.1. Project Configuration File
6.2. Change Attribute
6.3. Network Files
6.4. DMT Implications
6.5. Test Implications
6.6. Cross Compiling
6.7. File Version by Architecture
7. Reminders
7.1. Awaiting Development
7.2. Being Developed
7.3. Being Reviewed
7.4. Awaiting Integration
11. Geographically Distributed Development
1. Introduction
1.1. Risk Reduction
1.2. What to Send
1.3. Methods and Topologies
1.4. The Rest of this Chapter
2. Manual Operation
2.1. Manual Send
2.2. Sending Baselines
2.3. Sending Branches
2.4. Manual Receive
2.5. Getting Started
3. Sneaker Net
4. Automatic Operation
4.1. Sending
4.2. Receiving
5. World Wide Web
5.1. Server
5.2. Browser
5.3. Hands-Free Tracking
6. Security
6.1. Trojan Horses
6.2. PGP
6.3. Sorcerer's Apprentice
7. Patches
7.1. Send
7.2. Receive
7.3. Limitations
12. Further Reading
1. Software Configuration Management
2. Reviewing
A. New Project Quick Reference
1. Create the Project
1.1. Add the Staff
1.2. Project Attributes
2. Create Change One
3. Develop Change One
4. Review The Change
5. Integrate the Change
6. What to do Next
B. Glossary
C. Why is Aegis Set-Uid-Root?
1. Examples
2. Source Details
D. Internationalization and Localization
1. The “.po” Files
2. Checking the Code
3. Translators Welcome
E. GNU General Public License
1. Preamble
2. TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2.1. Section 0
2.2. Section 1
2.3. Section 2
2.4. Section 3
2.5. Section 4
2.6. Section 5
2.7. Section 6
2.8. Section 7
2.9. Section 8
2.10. Section 9
2.11. Section 10
2.12. NO WARRANTY Section 11
2.13. Section 12
3. How to Apply These Terms to Your New Programs

List of Figures

2.1. Flow of Files through the Model
2.2. Change States and Transitions
   Next
   Chapter 1. Introduction