THIS PAGE IS OBSOLETE
The following examples describe how to use the make and cvs tools. This very short guide is not intended as a replacement for the corresponding manuals.
Make is a utility for building and maintaining programs. In a more general definition, it can be described as a dependency management tool (in the sense that is controls how targets are updated when dependencies change).
Make is especially useful for managing large programs, in which multiple, often not obvious, dependencies occur.
In general, make reads its rules from a "makefile", but it may be built with implicit rules for frequently used tasks. A makefile is a sequence of definitions (of variables, rules, and directives). The first explicit rule is the default (i.e., the one whose target is to be built if no target is specified).
Below, the most usual features are covered (other features, such as conditionals and cycles are not, since they are not of special interest in most cases).
Make variables may be initialized with literals or with the result of commands. The following definitions have the same result (assuming that the directory contains source files named file1.src through fileN.src.
SRCFILES = file1.src file2.src ... fileN.src <----- literal initialization SRCFILES = $(wildcard *.src) <----- wildcard initialization SRCFILES = $(shell ls *.src) <----- use output of shell command
Access to a variable is done by using the $ sign followed by a single character (if the variable name has more than one character, then it must appear in parenthesis). In addition to user-defined variables, make also defines automatic (pseudo-)variables (the list is not exhaustive).
$(SRCFILES) <----- access to variable SRCFILES $< <----- first dependency (pseudo-variable) $^ <----- all dependencies (pseudo-variable) $* <----- pattern match (pseudo-variable) $@ <----- current target name (pseudo-variable)
Some variables are pre-defined by most make distributions. These are normal variables and may be redefined by the user. The following list shows some of the most common (the list is not exhaustive).
A variable may be defined based on another: for instance, considering the above SRCFILES variable, we could define a new list by editing the previous one, replacing the .src with another (in our example, with .der, for "derived").
DERFILES = $(SRCFILES:%.src=%.der)
The general syntax of a rule is as follows (target is supposed to be "built" by the commands 1 though N):
target: dependency1 dependency2 ... dependencyK
command1
command2
...
commandN
There are two types of rules: implicit, which make uses for derived building targets from derived (calculated) dependencies; and explicit, in which both targets and dependencies are specified.
The following is an example of an implicit rule for obtaining a compiled (.o) file from a C++ (.cpp) source, by simple compilation. Variable CXXFLAGS is used to specify compilation flags and CXX is the compiler's name (g++ by default).
CXXFLAGS=-ggdb -O3
%.o: %.cpp
$(CXX) $(CXXFLAGS) -c $*.c -o $*.o
In this rule, % represents a pattern (the same pattern appears in the commands section represented by the $* pseudo-variable).
The same rule could be written thus (here $< represents the first dependency, and $@ the target to be built by the rule):
%.o: %.cpp
$(CXX) $(CXXFLAGS) -c $< -o $@
a.o: a.cpp x.h y.h
b.o: b.cpp x.h
$(CXX) -DSPECIAL $(CXXFLAGS) -c $< -o $@
Additional dependencies cannot be specified in the above rule, but, since make accumulates the dependencies for a given target, additional dependencies may be specified by compatible rules. These additional rules do not need a section with commands (the commands in the implicit rule will be used). Nevertheless, if there are commands in both an implicit and an explicit rule, the explicit's are used. In the first example, a.cpp would depend on x.h and y.h, while b.cpp would depend on just x.h and use a special compilation command.
Comparable explicit rules would be:
a.o: a.cpp x.h y.h
$(CXX) $(CXXFLAGS) -c $< -o $@
b.o: b.cpp x.h
$(CXX) -DSPECIAL $(CXXFLAGS) -c $< -o $@
Note that in the case of implicit rules (the most frequent), file dependencies can be computed automatically, for instance with GCC. The following examples assume that all files are in the current directory. If they are not, then the second set of examples could be used (CXXFILES is a variable containing the list of C++ source files:
g++ -M *.cpp <--- computes all dependencies (system and local) g++ -MM *.cpp <--- computes all dependencies (only local dependencies)
g++ -M $(CXXFILES) <--- computes all dependencies (system and local) g++ -MM $(CXXFILES) <--- computes all dependencies (only local dependencies)
Of course, it is possible to build a rule for updating the dependencies and many projects do it:
depend:
$(CXX) -MM $(CXXFLAGS) $(CXXFILES) > .makedeps
-include .makedeps
The minus (-) sign before the include instruction indicates that processing should not stop if .makedeps does not exist (normally, and if nothing is told otherwise, make stops when an error occurs).
This is a very short introduction to CVS, the Concurrent Versions System. Further information should be obtained from the official sources and manuals.
File:CVSInteractions.png CVS defines a source repository that will be the hub for all the entities involved in a project. Each entity will request a module (in CVS parlance, a directory belonging to a tree controlled by the repository) to work on locally. Then, each local copy may be the object of several editing and management operations for keeping it in sync with the repository. Since changes are concurrent, compatibility problems may arise during the life of a local copy, until it again becomes synchronized with the central repository (see image).
The first contact with CVS may depend on the specific project and participants: the repository and/or the project may not yet exist (and have to be created), or they may both already exist (in which case, only check-out, update, and commit operations are performed).
The repository's location may be specified directly as an option to the "cvs" command: <bash>
cvs -d /root/of/the/cvs/repository some-cvs-subcommand
</bash> Or it may be read from the CVSROOT environment variable (defined, for instance, in the shell's configuration file): <bash>
export CVSROOT=/root/of/the/cvs/repository cvs some-cvs-subcommand
</bash> Various modes of access are possible: local (i.e., direct access to the CVS repository's file system exists) or remote (otherwise). Remote access may be done through CVS's own protocol (pserver), but this is insecure. Another remote access method is the one specified by the CVS_RSH command (which defines the method for extended access methods). A common definition for this variable (in fact, the default in some systems) is "ssh": <bash>
export CVS_RSH=ssh
</bash> The CVSROOT variable now can be written as: <bash>
export CVSROOT=:ext:username@compiladores.rnl.ist.utl.pt:/root/of/the/remote/cvs/repository
</bash>
The repository manages files by giving them revision numbers. Special tags may be used to group various files in various satges of evolution, creating snapshots of the repository's state for further reference. The default tag (corresponding to the most recent versions) is called HEAD.
Interaction with the repository is done by first performing a "check-out" operation (for obtaining a local copy) and, then, through a cycle of "update"/"commit" operations. A "release" operation may or may not be needed (when the local copy is no longer needed).
The following command is almost never used and is presented here just for reference (we assume that the CVSROOT variable has been defined): <bash>
cvs init
</bash> This command creates a special control module (in the directory specified by the CVSROOT variable) called CVSROOT. This module will control how CVS manages each of the projects and files in the repository.
A new CVS module may be created from a source tree (assumed outside CVS control) as explained below. We assume that the future module contents are in the /some/directory/to/be/imported directory.
<bash>
cd /some/directory/to/be/imported cvs import module-name vendor-tag initial-release-tag
</bash>
Where module-name is the name of the new module (e.g. the project's name), vendor-tag is a label (e.g. a nickname of an acronym of the author or context), and initial-release-tag is the initial tag (e.g. "initial").
Note that the import operation does not automatically put the imported contents under CVS control: it is still necessary to check them out from the repository. Also, note that the import operation is recursive and that executing it without care may result in uploading trash (i.e., unwanted material) into the repository: ensure that the command is given inside the directory to be imported (as shown in the example).
If the module/project is already in the repository (even if it is empty), no import operation is needed (see the "add" operation below).
The check out command creates a local copy of a module in the repository:
cvs co module-name
The update operation synchronizes a local copy with the contents of the module on the repository. The synchronization process may cause new files to be downloaded into the local copy, obsolete files to be removed and existing files to be changed. Of course, the process may run into difficulties if the local copy and the information coming from the repository cannot be merged without conflicts.
cvs update
CVS tells the user about the state of the update process by prefixing each file name (in the log of its actions) with a single character: U (new file coming from the repository), P (local file patched to reflect changes in the repository), R (local file scheduled for removal, but still exists in the corresponding repository revision), A (local file scheduled for addition, but not yet commited), C (a conflict was detected and marked: manual intervention is needed), ? (unknown local file). Other messages may also be given (for instance, telling about the removal of local files).
When solving a conflict, the user must first select the version to keep in the local copy and only then proceed to committing local changes.
If, during the life of a module, a new file is added to the project, then the local file must be added to the repository. This is done by the following command:
cvs add name-of-local-file
Note that the command does not change the repository (it only marks the file for addition at the next commit operation).
Local directories must be added before their contents may be added. Adding a directory creates a local CVS subdirectory for keeping information about its contents.
First and foremost: the CVS repository NEVER removes any files. This is because, even if a file becomes obsolete, there were past versions of the project in which the file exists and it must be possible to recreate it. Nevertheless, it is possible to mark it as deleted, so that it no longer appears in newer versions.
The command to schedule a file removal is:
cvs remove name-of-local-file
Note that CVS complains if the file still exists (this means that, for the previous command to work, the file must first be removed).
The commit operation is, arguably, the most important, since it is the one that changes the repository's contents and makes the project evolve:
cvs commit
The commit operation allows the user to input a message that will be inserted in the log of changes made to the project. The commit operation is, by default, recursive and allows a different log message to be registered for each local directory in the project tree.
In addition to the above basic commands, other are available, for instance, for tagging revisions and inspecting the repository. Further information may be obtained in the manual:
man cvs info cvs
