Exercise 6: CVS, Makefiles, Project 1 Part 1

This exercise is an introduction to CVS, make and makefiles, and is also the first part of Project 1. Understanding make and makefiles is a prerequisite for Project 1, and while carrying out the makefile exercise you also get to work on array-valued functions that are needed for the project.

Project 1 brings together a number of components from the first five Sections of the course, and is a comprehensive test of what you (should ;-) have learnt so far. In particular, it tests your ability to handle a reasonably large project, by focusing sometimes on the big picture, sometimes on the small pieces.

The situation is similar to one you would (will) encounter in a collaborative programming project. You are responsible for completing a larger program, by collecting a number of program pieces, and then adding some missing parts.

You may assume that the pieces you get have been tested and are working correctly. Correspondingly, it is your responsibility to make sure, by testing, that the pieces you add or modify are working as intended.

First be sure to pick up your bonus points!   Credits: 5/5

This time, you will use CVS (Concurrent Versions System) to pick up the exercise material from a directory, importing it into a private CVS repository, and then extract a working copy into the directory where you will work on Project 1.

• Edit your ~/.cshrc or ~/.bashrc file, and add (or replace) the following lines, that set the environment variables CVSROOT and EDITOR:

  setenv CVSROOT $HOME/cvs                  (for .cshrc users)
  setenv EDITOR your-favorite-editor
  
  export CVSROOT="$HOME/cvs"                (for .bashrc users)
  export EDITOR="your-favorite-editor"
  

  NOTE: if you want to have access to your own repository from home, please read this

  where your-favorite-editor could be, for example, nedit, kedit, kate, or xemacs

• Then "source" the ~/.cshrc or ~/.bashrc file (do this in all open terminal windows, or at least the ones that you will use for CVS commands):

  source ~/.cshrc       (for .cshrc users)
  
  source ~/.bashrc      (for .bashrc users)
  

• Initialize the CVS repository (this creates the directory you specified as CVSROOT and puts some standard CVS files in a subdirectory of it), by giving the following command in a terminal window:

  cvs init
  

• Change directory to the ComputerPhysics directory and do "cvs update -d" to get the Section 6 material:

  cd ~/ComputerPhysics
  cvs update -d
  

• Change directory to the 6_Programming directory and import the files there to your own CVS repository, as module Project1

  cd 6_Programming
  cvs import -m initial Project1 cph initial
  

• Change directory to your home directory, check out a copy of the CVS module, and move it down into the ComputerPhysics hierarchy:

  cd
  cvs checkout Project1
  chmod g-rx Project1
  mv Project1 ComputerPhysics
  

  (the chmod command makes your project directory inaccessible to others in the group).

• You should now have a subdirectory ComputerPhysics/Project1, with the files needed for this weeks exercise:

  cd ComputerPhysics/Project1
  ls -l
  

• Just for fun, take a look at the files where CVS stores its information:

  cat CVS/Repository
  cat CVS/Root
  cat CVS/Entries
  

  Normally, one does not need to worry about these files. Nevertheless, it may be good to be aware of CVS' order of preferences:

  1. If CVS/Repository exists, that is the repository ("no matter what").
  2. If not, CVS checks if a location for the repository is given directly on the command line, with "cvs -d /home/... ...", for example.
  3. If not, CVS looks for the CVSROOT environment variable.

  So, there is the explanation for how CVS can "remember" where a module came from, and for why the environment variable $CVSROOT (or the -d option) is only used when a module is created or checked out.

• Now, just to have a chance to try the most common CVS commands that are used while updating files, you should make a small change to the files in the Project1 directory. Replace the first comment line of each file with one that contains the characters $Id$ (NOTE: upper case I, lower case d). Thus, in the Fortran files, the line should become, for example:

  ! $Id$
  

• Now that you have made some changes to the files, you can show the differences relative to the repository versions by doing

  cvs diff
  

  Note that "your" lines are preceded with > , while the lines from the repository version are preceded by < .

• Now "take a snapshot"; i.e., update the repository files, by doing

  cvs commit
  

  Your favorite editor will start, and you are requested to enter a line or two with comments about the snapshot. After entering the comment and exiting from the editor, the CVS repository will be updated, and you thus have a new snapshot of your directory.

  • Note that the lines starting with CVS: are removed automatically, so don't start you own comments lines that way.

  If you prefer to not use the editor to enter the comment you may enter it directly on the command line, with the -m option (note that quotation marks are needed):

  cvs commit -m 'type the comment here'
  

  You can check that the repository is up-to-date by again doing

  cvs diff
  

• Take a look in the files again with an editor, and note that the $Id$ string has now been replaced with a string that contains the date and the CVS version number. Also note that the same string occurs in a character command a bit further down in the Fortran files. The character variables are printed when the program runs, thus documenting which versions of the codes that were compiled.

• In the future, whenever you feel that a snapshot would be useful, for example when you have made an update that more or less works, take a snapshot by doing

  cvs commit
  

• It is the files that you originally imported that are updated in the CVS repository, not all the files in the directory. If you make a new file that you would like to also keep in the repository (the integral_test.f90 file that you will create below is a good example), do

  cvs add the-file
  

  After the next commit, the file will be part of the repository, along with the files that were already there.

If you would like to read more about CVS or tkcvs, or look up details about a command, there are links and on-line documentation. Or, find out how to download WinCVS, MacCVS, TortoiseCVS or tkcvs.  

Your starting point for this part of the exercise is an example that illustrates array-valued functions, Fortran modules, and UNIX makefiles. The example is built around an array-valued function for spline derivatives. After having pondered enough upon the example to understand the relation between the files involved, you are to add a set of similar routines for spline integrals.

• Start by looking through the files (in splines.f90 you need not worry about most of the code; just look at the declarations and the way the function returns the result) with your favorite editor:
  • derivative_test.f90
  • splines.f90
  • Makefile

• Consider the relations between the files:
  • The program derivative_test calculates function values y(i) for a third order function, calls the spline_derivative array-valued function, and compares the result with the analytical answer.
  • The splines.f90 module contains the spline_derivative function, that returns the derivatives d(i) of a cubic spline through the function values y(i).
  • The Makefile describes the relations between the files, including the object file splines.o, that is the result of compiling splines.f90.

       gfortran splines.f90 derivative_test.f90 
       ./a.out

However, to help introduce you to and try out a makefile that you will need anyway, the skeleton Makefile should be used to run the test.

• Run the test, by issuing the command make in a UNIX command window. Watch the resulting compilations (producing .o files), linking (produces the executable .x file), and execution (should come out with an OK).

To check that you understand the makefile relations and the notations used to describe them, please answer the following questions (if you are uncertain about these questions, review the subsection about makefiles in the Section 6 lecture notes):

In the following relation, which is the target? derivative_test derivative_test.x Credits: 2/-1 OK

derivative_test: derivative_test.x
        derivative_test.x

What is derivative_test.x in the same relation? target   dependent   rule   Credits: 2/-1 OK

In the relation below, which is the target? derivative_test.x $(DERIVATIVE_TEST) Credits: 2/-1 OK

derivative_test.x: $(DERIVATIVE_TEST)
        $(FC) $(FFLAGS) $(DERIVATIVE_TEST) -o derivative_test.x

Which is the dependent of derivative_test.o? derivative_test.f90 derivative_test.x Credits: 2/-1 OK




If you were to make a small change to derivative_test.f90 (such as adding a blank line or character), which files would be regenerated by a make command? none   derivative_test.o   derivative_test.x   Credits: 2/-1 OK

The clean target is often present in Makefiles (this is by convention, not by requirement). As the name suggests, it is used to clean-up; i.e., remove all files that can easily be reconstructed -- basically all files that result from compilation. As it stands, your Makefile does not remove certain files. To find out which ones, run "make", then run "make clean", then run "cvs -n update". The "cvs -n update" does nothing, but shows what would be done by "cvs update". As a useful side effect, it shows files that CVS knows nothing about, with a question mark in front.

• Add the appropriate "*.something" to the clean method, and then

  
  

  I have updated the makefile to make a proper clean Locate and upload your Makefile file: Credits: 2/-1 OK

As supplied, the spline_derivative function has the three arguments x, y, n, where n is the number of elements in the arrays x and y. By using the Fortran-90 standard function SIZE(a), that returns the number of elements in the array a, you may eliminate the need to pass n in the argument list.

Which files need to be changed ? splines.f90   derivative_test.f90   Credits: 1/-2 OK


Carry out the changes, and rerun the make command.

If it didn't run OK you may need this hint   Credits: -1/-1

You should now have enough experience to carry out the next step; to write an array-valued function named spline_integral, that returns the integral of a spline, defined by its function values and derivatives at a number of 'knots', x(i).

The function should return an array with SIZE(x) elements. Each element is equal to the integral of f(x) from x(1) to x(i) (the first value is thus always zero). f(x) is the cubic spline through the given function values y(i) at the knots x(i).

• To specify the spline one needs, in addition to the arrays x(i) and y(i), the derivatives d(i). These are to be obtained through a call to spline_derivative

  
  

  you should not need a hint on how to do it [-1]   Credits: -1/-1

  but you might need one about where to store the answer [-1]   Credits: -1/-1

The spline_integral itself should be callable as follows:

        q = spline_integral (x, y)

i.e, it too should use the SIZE() function to specify the number of elements in x and y (and in the result). The formula to use for the integral is in the lecture notes.

In terms of files, you need to change and / or create the following files:

• splines.f90
• integral_test.f90
• Makefile

If all goes well, you should be able to run the test with the command make integral_test, or just make, if you made a smart update of the Makefile.

A hint is available [-1]   Credits: -1/-1

The plain "make" command should run first the derivate test, then the integral test (since the latter depends on the former).

If everything seems OK, but you get NOK for an answer, then maybe this hint helps [-1]   Credits: -1/-1

The last points are given when you submit the working source code for our inspection:

Here is my working version of the spline_integral routine -- it is included in splines.f90 Locate and upload your splines.f90 file: Credits: 5/-5 OK

When you are done with the points above you have Project 1 well in hand. The physics and programming aspects of the project are presented in the next lecture, and the next exercise file contains the instructions for finishing the project.

One of the programming aspects that is central in the project is how to fill in values in an array, row-wise and column-wise. To help you prepare for this, here are a two examples.

• filling in values row-wise
• filling in values column-wise

It may be a good idea to print these out from your browser, study them, and try to guess what the output would be when executed. You can also save them in your Project1 directory, compile and execute them, and check if your guess was correct.

It is also a good idea to (re-)read the sections in your Fortran book about array indexing and argument passing, especially about "assumed-shape" arrays, "automatic arrays", and "allocatable arrays".