ECE 264 Exercise 2

Multiple Files and Version Control with Subversion

All non-trivial programs are developed in stages, namely with different versions. Version control is essential for a team project. Even if you work alone, you still want to use version control to keep a copy of the latest stable working program while adding new features. A common problem among students is that their programs do not work any more (syntax error or run-time crash) when the submission deadline is approaching. With version control, the students can easily roll back to the previous working version and receive most points. With version control, you can make line-by-line comparison to determine what is wrong in the new version. You can use version control to synchronize the code at home and at school. 

This exercise also shows how to write a program that uses multiple files. As your programs become more complex, it is natural to divide the programs into multiple files.

Additional Information: This exercise provides enough information to use subversion. If you want to learn more, you can find many web sites.  This web site contains some common commands for subversion. You can find an on-line book. The book covers much more details.  For this exercise and the rest of this class, you do not need the details described in the book. If you use Eclipse, you can install subclipse.

Create Repository and Import

Please follow these commands precisely. If you skip or modify the commands, you may have encounter error messages.

1. create a repository:

enter your course account

cd          # comment: return to the home directory, italic means the command you type

svnadmin create repository

# You will see two directories: one is called repository and the other is .subversion. Use "ls -a" to see hidden (starting with .) files and directories.

# If you do not see .subversion, that is all right. You can still move forward.

pwd        # the current directory, call it x, it is something like /home/shay/a/ece264a3

2. download the following files and store them in the directory ~/temp/              # ~/ means the home directory

hello.h

main.c

2. cd         # return to the home directory
3. setenv EDITOR emacs      # make emacs your default editor (EDITOR upper case). If you prefer vi, replace "emacs" by "vi".
4. svn import temp file:///x/repository/exercise/E2      # replace x by /home/shay/a...

An editor (emacs) appears. Type "create the entry for exercise 2." Save and exit the editor.

The following message will appear on screen:

Adding         temp/main.c
Adding         temp/hello.h

Committed revision 1. 

file:/// is one of several ways to access files in svn. You can check this table for other methods.

6.  svn list file:///x/repository/                         # You will see "exercise."  This means import is successful. Remember to replace x by your own directory
7. svn list file:///x/repository/exercise             # You will see "E2."
8. Now, you can remove the temp directory and all files inside.

cd

rm -f -r temp

9. svn checkout file:///x/repository/exercise/E2                    # check out the project from the repository

You can see (use "ls") a directory called E2.  Enter that directory (type "cd E2").

Program with Multiple Files

This program has two files, one source file main.c and one header file hello.h. The header file declares a function sayHello. At the top of main.c, there is a line

#include "hello.h"

This allows the main function to call sayHello.  To compile this program, type

                            gcc -Wall main.c -o E2

This means using gcc as the compiler and turns on the warning messages (-Wall). The input file is main.c and the output file is called E2.  E2 is an executable. If you type

                            file E2

The result will be something like "LSB executable ...for GNU/Linux ..."  This actual message depends on the machine. Delete this file

                            rm E2

Add a File to the Program

Next, we are going to add a line in hello.h after sayHello

                          void sayBye(int x);

We also add a new source file called bye.c. (Download this file.) Add the following line in main.c just above return 0;

                          sayBye(264);

Now, you should have three files: main.c, bye.c, and hello.h. Type

                          svn status

and you will see

                         ? bye.c

This means that subversion does not know anything about bye.c.  Additionally, you also see

                         M main.c

                         M hello.h

because the two files have been modified. Type

                        svn diff main.c

and you can see "+"  at the beginning of the newly added line. This command tells you what has been changed in a file.  You can also type

                        svn diff

and it tells you both hello.h and main.c have been changed.

Compile and Link Files

You cannot type

                        gcc -Wall main.c -o E2

because the program needs both main.c and bye.c now. You can create the executable in two ways. First

                        gcc -Wall main.c bye.c -o E2

The second method requires three steps

                       gcc -Wall -c main.c

                       gcc -Wall -c bye.c

                       gcc -Wall main.o bye.o -o E2

The first two steps compile the source files and generate the object files. They are called main.o and bye.o.  The third step links the two object files and creates the executable E2. Why would you do the same thing using three steps instead of one? This will become clearer when we explain Makefile later.

If you execute the program E2 by typing

                       ./E2

the output is

                      Hello

                      good bye 264

Commit Changes to Repository

Next, we are going to write the changes to the repository. First, add bye.c by typing

                      svn add bye.c

and you will see the message

                      A bye.c

Commit the changes by typing

                     svn commit

An editor appears and it includes three files below

                   -- This line ...

A bye.c

M main.c

M hello.h

Add a message "add a new function in file bye.c."  Exit the editor and you will see the following message

Adding         bye.c
Sending        hello.h
Sending        main.c
Transmitting file data ...
Committed revision 2. 

What to Submit?

Submit the outputs of the following four commands in Blackboard

1. svn log
2. svn log main.c
3. svn log hello.h
4. svn log bye.c

Extension

In this exercise, you are doing everything on the same computer. The true value of version control is to manage code when several people work together through a network. Version control makes open-source software possible. You can search "svn + ssh" on the Internet to learn how to set up a repository that can be used through the Internet. This is particularly helpful if you want to synchronize code between home and school.  If you sometimes write code at home and sometimes at school, you may forget which is the latest version. Copying code back and forth runs the risk of erasing the latest version. Version control is an ideal tool for this purpose.

FAQ

Q: How does version control help me?

A: This situation happens every semester. A student tells a professor, "My program was working fine yesterday. It does not work today and it is due today. What should I do?"  If the student has the program managed by version control, the student can roll back to the previous version and submit it. The student can probably receive most points. 

Q: Why do we need version control? I can just zip the files everyday.

A: Sometimes, you want to see what changes have been made. Version control allows you to compare different versions easily. You cannot easily compare the differences between two zip files.

Q: Can several people work on the same project? Will version control help?

A: Yes. Version control can merge changes from different people. In fact, some people claim that CVS (concurrent version system) is the foundation of today's open source software.  Many open-source programs, such as Linux and gcc, are developed using CVS. CVS has some limitations and SVN is considered a potential replacement of CVS.

Q: When should I commit?

A: You should commit often.  You should commit after you finish something, such as a feature or a bug fix. You should not commit buggy code because other people may update and see the buggy code. To prevent this, you should work on one task at any moment, finish it, and commit. When you are not sure, commit. It is easier to ignore a version that contains bugs. If you do not commit, version control cannot help.  It is probably a good habit to commit at least once everyday.

Q: What should I say in the commit message?

A: Describe what has been done. The message can help you find the version about the completed task, when it is add, who adds it, what is added before or after this task, etc.

Q: When should I update?

A: Update allows you to see the commit done by other people. You should update frequently to detect conflicts early.

Q: Do companies use version control?

A: Absolutely. If a company does not use version control, the company does not care about their source code and you should not join the company. Companies may use different version control tools.  Popular tools include CVS, SVN, Clearcase, Perforce ... You can find a comparison of some tools.  Some companies use version history as an indication of employee performance. "If you do not commit anything, you are not doing anything and should be fire." 

Q: Why does ECE 264 require SVN in only one exercise? Why doesn't the instructor require SVN in every assignment?

A: There are many version control tools. You can choose the one you prefer. You already know SVN and should use it for your own benefit.

Q: Can you use version control for something that is not a program?

A: Yes. You can use version control for anything that may be developed in stages and have "versions", for example, your project reports.

Q: Do you actually use version control?

A: Yes, all lecture notes in ECE 264 (written in latex) are managed by CVS.