Introductory Text for Intermediate Programming

Transcription

1 Introductory Text for Intermediate Programming Andreas Keese Dominik Jürgens Jewgeni Rose Institut für Wissenschaftliches Rechnen Technische Universität Braunschweig October 10, 2013

2

3 Contents 1 General Remarks How to read this Text The Working Environment UNIX Notes on Additional Literature UNIX command line Where do I get a command line? Fundamentals The Help System The Program man The Program apropos Manpage Sections Editors in UNIX Text Editors First Steps with the Compiler The First Program Compiler Warnings Tools in Software Engineering Build Tool Ant Jar Files HelloWord with Ant Using properties within build.xml Using external libraries Version Control Subversion The Repository The working copy Working on a Working Copy A Repository with multiple users Multiple Working Copies, Conflicts and their resolution

4

5 1 General Remarks This text contains introductory information for the course Intermediate Programming at Technische Universität Braunschweig. This course consists of some labs without lecture. Website pages at To stay in contact with our students and to announce news we use our web If you take part in this course you should check that site occasionally to be informed about any changes. Prerequisites Knowledge of another object-oriented programming language is necessary, however this text also references other introductory texts to help students who do not have much programming experience. Listenership The Listenership of this course has varying backgrounds. Electrical engineering takes a large part, but other scientific or engineering fields are present. Because of this scientific and technical oriented listenership no advanced developing environment will be used. It would distract from the software developing process. Learning targets You should learn the following in this course: programming algorithms and data structures in Java develop and extend applications use and develop data structures getting to know software development tools the JDK (Java Development Kit) getting to know software engineering tools version- and configuration management (Subversion) tools to compile complex programs (Ant) 5

6 1 General Remarks Software development tools If you want to understand the function of software development tools it would be very hindering to use development environments like Netbeans or Eclipse. In this course we use the minimal toolset, which is used in big development environments as well, albeit hidden behind the curtains. Participants in this course should not use integrated development environments. Working Environment Java is a platform-independent language. That is, Java allows a programm to be written on one operating system and to be executed on a different one. The only requirements are JDKs available on both systems. In a scientific and technical working environment you will be confronted with different operating systems and most will be Unix-like, especially if you are developing embedded systems or other nonstandard computing devices. In this course, we choose Linux as the development platform. Linux is a free, open-source Unix derivative. Participants in this course a strongly encouraged to work with Linux throughout the course. Using your own computer for this course You can of course use your own computer to work in this course, but you will have to use a UNIX environment, since this course includes learning to work in that environment. If you do not have Linux installed on your computer, choose one of the following alternatives to get a Linux working environment: Virtual Machine On our website we provide a tutorial for installing a virtual machine (menu on the left side, bottom VM ) which has a similar configuration as the computers in the lab room. Cygwin At you can download a UNIX environment for Windows. Install at least the following packages by executing the file setup.exe: subversion, make, man, bash, cygwin-doc and all of their dependencies. After installation you can start the command line interpreter by using its start menu entry. Instant Linux There are several Linux versions which you can start directly from CD or DVD without having to install anything. You can find one at knoppix.net/. Installing Linux You could install any Linux version of your choice directly to your harddrive, but that would be to much of an effort just for this course. 1.1 How to read this Text The present text is not meant to be a text book on programming with the language Java. For this purpose we recommend a dedicated text book which aims at teaching the language. 6

7 1.1 How to read this Text Recommended Literature There are plenty of books about Java, for example Java, A Beginner s Guide by Herbert Schildt and Java The Complete Reference (for a more comprehensive view) also by Herbert Schildt, which both are officially endorsed by Oracle, the manufacturer of Java. In the particular exercises of this course we will reference sections of the online book Introduction to Programming Using Java by David J. Eck ( javanotes/). The book is suitable for beginners and also experienced programmers who are still new to Java. Online Documentation Besides the aforementioned literature, your most important resource will be the online documentation of the Java platform, which is hosted at Oracle s website. Java provides a comprehensive, well-documented standard library. Therefore, whenever you encounter an unknown class in one of the exercises, you should first read its documentation at Furthermore, at Oracle provides tutorials which deal with specific aspects of Java. You might be interested in reading the first four tutorials of the section Trails Covering the Basics. Please note that many of the available books and tutorials will advise you to use an integrated development environment (IDE). However, while those IDEs certainly save you work, they also hide important details from you, which are essential to learning the basic principles of Java. Therefore, please refrain from using an IDE during this course. Structure of this Text At the beginning the text gives a guided introduction to the use of Unix systems. If you are already familiar to Linux, you may skip that part. In chapter 3 we will introduce the Java compiler, followed by the chapter 4 which deals with the build tool Ant and the version control system Subversion. These tools will also be used during this course. This text is meant to be read at a computer so that you can directly try out commands explained in the text. 7

8

9 2 The Working Environment UNIX 2.1 Notes on Additional Literature This chapter is intended to give a basic overview of the usage of the Unix command line. Therefore, some details are skipped. For those who have problems understanding some of the explanations, we provide a list of more in-detail literature at the website of the course ( Unix-Books, UNIX command line Historically the command line is much more prevalent in UNIX. That is due to the fact, that at the time of UNIX s creation the computer hardware simply was not capable of displaying graphics. Thus many users consider the command line to be a archaic tool, but using it still has some advantages over graphical user interfaces today. After having come in contact with the system you will learn that things you thought to be impossible using a graphical interface are quite easy to perform in a elegant way on the command line. You could for example combine two programs into a new one (see section 2.2.2). The command line is simply a program which accepts text input, interprets it and outputs the results as text. You can think of the command line interpreter as a sort of servant, who accepts commands and executes them. Since the duty of that servant isn t simply cooking coffee, but simplifying the work with files on a computer he has some special characteristics. We ll call our servant here shell. The basics that you need to work through this course are summarised in the following chapter Where do I get a command line? Modern Linux versions follow the trend to hide the command line from the user to not frighten beginners. To find the command line you will need to search through the subfolders of the start menu and look for something called Terminal or Console. If you start this terminal you will get a little window with the following content: username@machine: $ In this window you can type commands and the shell running inside of it will interpret and execute them. 9

10 2 The Working Environment UNIX Fundamentals Filesystem Abstract A filesystem is a system for managing files. Since files are a common concept in electronical data processing every operating system has such a filesystem. In an office you use folders for organising large quantities of data. For example in accounting you would have a folder labelled Accounting In this folder you should find all the documents you d expect. This system was introduced in computers as well; Windows-users might recognise the term folder. However on a computer you can have a subfolder inside of a folder, which is quite complicated (if not impossible) to achieve in an office. Since using the term folder isn t quite optimal to describe a filesystem concept, UNIX uses the term directory There are two ways to describe a filename with a path. You can have a relative path or an absolute path. The relative path is the path relative to the current location and the absolute path is the path from a global reference point. Absolute Paths In UNIX there is only one root directory called /, which is the just mentioned global reference point. From this reference point you can describe a path to any file on the computer. To describe a path through the directory in the filesystem UNIX has a special scheme. The scheme uses the symbol / to access the content of a directory, which was appointed in front of the /. The name /bin labels the directory with the name bin which is located directly in the root directory /. If you now want to access files or directories which are located inside the directory bin, you use the / again, this time as a separator to get the contents of the directory. /bin/ls is for example the path to the file ls located inside the directory bin in the root directory Relative Paths As mentioned above, you can describe paths relative. All you have to do is omit the reference point /. The directory you currently reside in is called working directory. The command pwd will give you your current location as an absolute path. the path test/testfile is the path to the file testfile which is located in the subdirectory test of the current working directory Special Symbols In every directory there is a way back. This way is represented by the symbol... Using.. as a path will get you one step back. Environment Variables Environment variables are special addresses inside the command line interpreter which can be assigned any value. You could for example define: 10

11 2.2 UNIX command line TEST=HELLO This assigns the value HELLO to the variable TEST If you want this variable to be used by other programs than the current command line interpreter you have to export it. This happen with the following command. export TEST You can combine definition and export of a variable in one line. export TEST=HELLO To get the current value of an environment variable you simply precede its name with a $. $TEST The above command will tell us that the interpreter does not recognise the command HELLO. So the interpreter interprets every input as a command. If you want to display the value of your variable you will need to use the echo command. It will output anything you put behind it. So the following command will display the current value of your variable. echo $TEST Starting Programs To start a program on the command line the command line interpreter needs to know where it is located. A list of directories containing programs is stored in the environment variable PATH. What programs are there? We just learned that the command line interpreter uses the environment variable PATH to look for programs. So we shall take a look at its value. echo $PATH We see that it contains several directories separated by a :. One of these is the directory /bin, which contains many important programs. With the command ls we can take a look at its contents. ls /bin As you can see the command ls resides in that directory as well. Important Commands This section should give you an overview of some important UNIX commands. list files ls will show the contents of a directory. change directory cd PATH changes into the given directory by PATH. create directory mkdir DIR will create the directory DIR. 11

12 2 The Working Environment UNIX remove directory rmdir will delete a directory. copy file cp SOURCE DESTINATION will copy the file SOURCE to DESTINATION. delete file rm FILE will delete FILE. move file mv SOURCE DEST will move SOURCE to DEST. How do I run a program? If we write our own programs we want to run them as well. But since our working directory is not included in the PATH variable we have to explicitly tell the command line interpreter where our program is located. This can be done in two ways. Either with an absolute path, which can be quite long and cumbersome to type every time, or with a relative path, which looks like this:./program The. stand for the current directory followed by a / to indicate that we want to access a file in the current directory and finally the name of our program. If you would have just put program there, the command line interpreter would have searched through the directories given in the PATH variable. Controlling Processes In this section we would like to show how to control programs at the command line. Process In UNIX every running program is represented by its process and associated process id (short PID). By knowing the PID of a specific running program you can control it with the kill command. If you don t know the PID already you can find it using the ps tool. Stopping Programs [ctrl+c]. To stop a running program you can press the key combination Input- and Output redirection, Pipelines Next we d like to show you the concept of input- and output redirection. With redirection you can sort of combine several UNIX-programs together. While programming this can be quite handy to search through compiler messages or other output. Nearly all UNIX shell programs work like this: they take input on their standard input stream stdin, process them and output the results on their standard output stream stdout. An input stream can be a file, keyboard input or the output of another program. An output stream can be the screen, a file or the input stream of another program. Usually the standard input stream is the keyboard and the standard output stream is the terminal in which the program was started. For example look at the command cat. 12

13 2.2 UNIX command line It copies data from it s standard input stream to it s standard output stream. Let s try it out: cat You will get a blinking cursor. Type some text and press the Return-key. Your input will be printed on the screen again. When you pressed Enter, cat copied your input (from the keyboard) to it s output screen (the terminal window). The fact that your input was already visible while typing shouldn t bother you here - it had nothing to do with cat. Enter some more lines - everytime you press Return, the input is copied to the output. Exit cat by pressing [ctrl+d]. The key combination [ctrl+d] tells cat that the input is finished and it can stop processing word of advice: [ctrl+d] and EOF (End of File), that you will get to know while coding C, are not the same however [ctrl+d] creates a EOF. Now we want to redirect the output of cat, that means we want to change it s output stream. If you want to redirect the output into a file, you put > filename after the command. Let s try it: cat > testfile Input some lines of text, each followed by Return. You might notice that now your text is not displayed a second time. That was expected, since the output stream of cat has been redirected from the screen to the file testfile. Finish your input by pressing [ctrl+d]. Use the ls command to verify that a file named testfile was created. To view the contents of that file we use again cat, but this time we redirect the input instead of the output. This is achieved by putting < filename after the command. Try it out: cat < testfile This should output your previously typed lines on the screen. You can combine this behaviour of cat to copy a file (although generally cp is used for this purpose): cat < testfile > testfilecopy This won t output anything on the screen. The input stream was the file testfile and the output stream was redirected into the file testfilecopy. Now check if the file was really copied: cat < testfilecopy This is the same as: cat testfilecopy This example works, because cat was programmed in a way that enables it to interpret the first parameter as filename for the input stream. 13

14 2 The Working Environment UNIX Following are some uses and examples for output redirection. The redirection of inputand output stream work with all UNIX programs, which work with the standard input and output streams 1. Try the following commands (If you want to know, what the sort command does, you can get help using the man command): ls > directory cat directory sort -r < directory What has happened here? We redirected the output of ls in a file and then used that file as input stream for the sort command. This command has sorted our file descending and outputted it to its output stream, our screen. With the help of the operator you can merge several output redirections. The operator redirects the output stream of the program on its left side into the input stream of the program on its right side. Since you can think of it as a sort of information pipeline between two programs, it s usually called pipeline-operator or short pipe. Constructs of the form command1 command2 work like the following sequence of commands, however without creating a temporary file: command1 > temporaryfile command2 < temporaryfile We can apply this to our example where we sorted the output of ls try the following commands: ls sort -r ls sort -r > sorted cat sorted ls -lf /usr/bin sort less The last line shows that you can combine as many pipelines as you like. Here the output of ls is redirected to sort, sorted and then passed to the less command. The less command outputs its input pagewise on the screen. You can exit it by pressing q. If you display something through less, you can scroll with the cursor keys up and down. Changing the command line language If you want to change the language of the command line, so that the programs man and apropos output german or english help texts, you have to change the environment variable LANG to the appropiate value. You can get the available languages with the command: 1 We will make use of that feature in our exercises to feed our programs with input. 14

15 2.3 The Help System locale -a This document assumes that your system is set to English. The easiest way to achieve this is to set the environment variable LANG to the value C. 2.3 The Help System There are several help systems availabe in UNIX systems. Especially while programming it s very helpfull to know at least know of them The Program man To get help for a UNIX command you can use the man command. Simply use the name of the program you want help for as the argument to the man command. You can even get help to the man command itself: man man On most systems you will first see a help text for the apropos command (which is part of man), but if you scroll with the space key, you will get to the help for man. You can exit this help by pressing q. To train the use of man, look at some other help pages. If you want to know more about the copy command cp or the directory listing command ls, try it: man cp man ls The Program apropos The above described form of the man command has one disadvantage: You can only get information about a command if you know its exact name. If you are looking for a command that does a specific task, but you don t know it s name, you can use apropos followed by a keyword to search. apropos will search through the short descriptions of all manpages and look for commands containing your keyword. If you are looking for general help you can try one of the following: apropos help apropos info apropos manual With every apropos command you will get a list of commands fitting the keyword with a short description. 15

16 2 The Working Environment UNIX Manpage Sections The output of apropos should be apart from the number in brackets self-explanatory. First in each line is the name of the described UNIX command, then there is in brackets a number and then a short description of the command. For example: sort(1) - Sorts files, merges files that are already sorted, and checks files to determine if they have been sorted. There are several lots of UNIX commands a typical UNIX system has around 12,000 commands documented by man. To keep track of those commands, they were put into different categories or sections. Every manpage, that man can display, resides in exactly one section. For example all commands that are meant for average users are in section 1, all system routines in section 2 and all standard C functions in section 3. The number in brackets tells you in which section a command is located. In the manpages of man you will find a description of all sections and their contents. 2.4 Editors in UNIX Text Editors To write programs you will have to edit files. There are quite a few different editors on our lab computers to do this. Have a look at the following programs and choose the one that fits you most: gedit SciTE emacs SciTE is an editor which simplifies the compilation and execution of Java programs. Furthermore this editor is well-documented and there are lots of extensions for it. Therefore, we recommand using SciTE during this course. You can start SciTE by typing SciTE & into the terminal. SciTE also has an entry in the application list of upper menu bar ( Entwicklung or Development ). You may configure SciTE according to your personal preferences, however, you have to choose Java as the source code language in order get appropriate syntax highlighting. Also, enable line numbers in order to ease 16

17 2.4 Editors in UNIX error tracking, as the compiler will provide you with a line number along with each error message. There are three importang shortcuts you may want to use: F5, F6 for compiling, and F7 for running a Java program (see menu Tools ). 17

18

19 3 First Steps with the Compiler A Java program consists of at least one class (keyword class). This class must contain the special method public static void main(string[] args). A class is usually defined in its own file, which is named after the class name plus the extension.java. On starting the programm, the Java interpreter will begin execution in the aforementioned main method. In order to execute your program, you will first have employ the compiler to generate a machine-readable version of the program (extension.class). This so-called bytecode will then be interpreted by the JVM (Java Virtual Machine), which actually executes the program. Both the compiler (javac) and the interpreter (java) are provided by the JDK, which is already installed on the computers of the lab room. 3.1 The First Program With the help of this simple example we demonstrate the way from the source code to the execution of a program. At first save the source code of listing 3.1 to a file named HelloWorld.java. 1 public class HelloWorld { 2 3 public static void main ( String [] args ) { 4 System. out. println (" Hello World!"); 5 } 6 } Listing 3.1: Ein einfaches Java-Programm - HelloWorld.java Then open a terminal und change 1 to the directory of the file you have just saved. Compile the file by executing the command javac HelloWorld.java in the terminal. This will result in a new file HelloWorld.class being created, which you can then execute by typing java HelloWorld into the terminal. The sample program will just output the text Hello World! at the terminal. 1 Use the command cd, which stands for change directory. 19

20 3 First Steps with the Compiler 3.2 Compiler Warnings The compiler usually gives an error message only for syntactic mistakes. It can also warn you of dangerous constructs in your program and help you correct logic mistakes by these means. Most of the time a warning means that the source code was syntactically (or grammatically ) correct, but probably does not do what you want it to do. Compiler warnings therefore should be respected in order to write correct programs. 20

21 4 Tools in Software Engineering 4.1 Build Tool Ant Compiling short programs like the Hello World example can be achieved by simply invoking the Java compiler javac. However, dealing with more complex programs distributed over several class files, directly invoking the compiler for each file and manually packaging the program would be cumbersome. Therefore you are to use Ant during this course, a tool which automates the task of building programs. Ant is an alternative to Makefiles and is especially used for Java software projects. You can download Ant from the Apache Software Foundation at Before proceeding, please make sure that Ant is installed on your system (on the computers of the lab room it already is). Otherwise follow the instructions of the installation manual at Simple Example Let us have a look at the HelloWorld program without Ant: 1 public class HelloWorld { 2 3 public static void main ( String [] args ) { 4 System. out. println (" Hello World!"); 5 } 6 } Listing 4.1: Hello World In large projects the source code is usually separated from its bytecode. Thus at first we create a directory for the source code (src) within our project directory helloworld. cd helloworld mkdir src All files which are created during the build process are to be stored in the directory build, the bytecode itself in build/classes: mkdir build mkdir build/classes 21

22 4 Tools in Software Engineering Now we are able to compile and execute our program javac -sourcepath src -d build/classes src/helloworld.java java -cp build/classes HelloWorld and we see the text Hello World! once again Jar Files Since it is common practice to package programs and program libraries as Jar archives, we are going to do that with our program as well. Additionally, in order to enable a simple execution of the program, we will make the Jar file executable. For that we need to create a so called Manifest file which determines the main class of the program that in our case is the only class HelloWorld. echo Main-Class: HelloWorld>manifest mkdir build/jar jar cfm build\jar\helloworld.jar manifest -C build\classes. java -jar build\jar\helloworld.jar Please execute the commands of the example verbatim without adding or omitting blanks HelloWord with Ant Until now we have organized our project using only basic Linux and Java commands. Now we are going to show how you can configure all the aforementioned steps within a single XML file which is then executed by Ant. The default name for this file is build.xml. We will also specify additional tasks, for example how to clean the project directory from previously compiled bytecode (.class) files. 22

23 4.1 Build Tool Ant 1 <project > 2 <target name =" clean "> 3 <delete dir =" build "/> 4 </ target > 5 6 <target name =" compile "> 7 <mkdir dir =" build / classes "/> 8 <javac srcdir =" src " destdir =" build / classes "/> 9 </ target > <target name =" jar "> 12 <mkdir dir =" build / jar "/> 13 <jar destfile =" build / jar / HelloWorld. jar " basedir =" build / classes "> 14 < manifest > 15 < attribute name ="Main - Class " value =" HelloWorld "/> 16 </ manifest > 17 </ jar > 18 </ target > <target name =" run "> 21 <java jar =" build / jar / HelloWorld. jar " fork =" true "/> 22 </ target > 23 </ project > Listing 4.2: Ant File of our HelloWorld Project build.xml Ant is invoked by the command ant at the terminal. Ant searches the current directory for the file build.xml. If there is no such file, it will recursively search all parent directories. In order to compile and execute our program using Ant, we have to type the following commands: ant compile ant jar ant run Or shorter: ant compile jar run Using properties within build.xml The above build.xml contains hard-coded values and therefore is not very flexible. Thus we are going to improve our build.xml file by using so-called properties to specify 23

24 4 Tools in Software Engineering certain configuration values, for example the name of the source directory and the main class. 1 <project name =" HelloWorld " basedir ="." default =" main "> 2 < property name =" src. dir " value =" src "/> 3 < property name =" build. dir " value =" build "/> 4 < property name =" classes. dir " 5 value ="${ build. dir }/ classes "/> 6 < property name =" jar. dir " value ="${ build. dir }/ jar "/> 7 < property name ="main - class " value =" HelloWorld "/> 8 9 <target name =" clean "> 10 <delete dir ="${ build. dir }"/> 11 </ target > <target name =" compile "> 14 <mkdir dir ="${ classes. dir }"/> 15 <javac srcdir ="${ src. dir }" 16 destdir ="${ classes. dir }"/> 17 </ target > <target name =" jar " depends =" compile "> 20 <mkdir dir ="${ jar. dir }"/> 21 <jar destfile ="${ jar. dir }/${ ant. project. name }. jar " 22 basedir ="${ classes. dir }"> 23 < manifest > 24 < attribute name ="Main - Class " 25 value ="${main - class }"/> 26 </ manifest > 27 </ jar > 28 </ target > <target name =" run " depends =" jar "> 31 <java jar ="${ jar. dir }/${ ant. project. name }. jar " 32 fork =" true "/> 33 </ target > <target name =" clean - build " depends ="clean, jar "/> 36 <target name =" main " depends =" clean, run "/> 37 </ project > Listing 4.3: Extended Configuration for HelloWorld build.xml On executing ant at the terminal, you will see the following output: 24

25 4.1 Build Tool Ant Buildfile: build.xml clean: compile: [mkdir] Created dir: /.../build/classes [javac] Compiling 1 source file to /.../build/classes jar: [mkdir] Created dir: /.../build/jar [jar] Building jar: /.../build/jar/helloworld.jar run: [java] Hello World main: BUILD SUCCESSFUL Using external libraries In larger software projects you may have to use external libraries which are not included in the Java standard library. Suppose you want to log the text Hello World to a file instead of printing it to a terminal. Logging functionality can be easily achieved using the log4j library. 1 import org. apache. log4j. Logger ; 2 import org. apache. log4j. BasicConfigurator ; 3 4 public class HelloWorld { 5 6 static Logger logger = 7 Logger. getlogger ( HelloWorld. class ); 8 9 public static void main ( String [] args ) { 10 BasicConfigurator. configure (); 11 logger. info (" Hello World!"); 12 } 13 } Since the location of log4j is not known to Ant at first (i.e. it is not included in the classpath of the compiler), compilation of the example will fail. Instead of directly manipulating the classpath, configure Ant via the build.xml file to include log4j in the build process: 25

26 4 Tools in Software Engineering 1 <project name =" HelloWorld " basedir ="." default =" main "> < property name =" lib. dir " value =" lib "/> 4 5 <path id=" classpath "> 6 <fileset dir ="${ lib. dir }" includes =" **/*. jar "/> 7 </ path > <target name =" compile "> 11 <mkdir dir ="${ classes. dir }"/> 12 <javac srcdir ="${ src. dir }" destdir ="${ classes. dir }" 13 classpathref =" classpath "/> 14 </ target > <target name =" run " depends =" jar "> 17 <java fork =" true " classname ="${main - class }"> 18 < classpath > 19 <path refid =" classpath "/> 20 <path location ="${ jar. dir }/${ ant. project. name }. jar "/> 21 </ classpath > 22 </ java > 23 </ target > </ project > Listing 4.4: HelloWorld with External Libraries build.xml Here we have configured Ant to include all libraries of a certain directory (lib/), in which we will also put the log4j Jar file. Executing the programm via ant will yield the following log4j-enhanced output: [java] 0 [main] INFO HelloWorld - Hello World In this section you have learned to organize your projects using Ant. Additionally there is a comprehensive manual for Ant with lots of examples provided by the Apache Software Foundation. Our examples are roughly adapted from this manual. 26

27 4.2 Version Control Subversion 4.2 Version Control Subversion In this chapter you will learn about the concept of version control. Managing versions of a program or of other documents is very important. Imagine for example the situation that you are working for this lab and one of the following events occur. data loss You program on your private notebook and from any reason, all the data from your hard disk get lost and your have to start all over again. synchronisation You work together with a colleague and you want to share the work load. team work You work together with your colleague on the exercises, and one little change by your colleague lets the program fail from one moment to the other. logging You and your colleague want to understand why you made a specific change in the past. branch You work on a program for some hours and suddenly you have an idea how to make the whole thing easier and better. Now you make the change and nothing works any more. Where to get the old working version from? It is easy to pretend that such events are a daily occurrence in large scale software projects. Motivated by this problems software engineering tools were invented which target one ore more of the mentioned problems. The superordinate concept to solve this problems is version-control. The currently most frequently used version control system is Subversion. It will be presented in this chapter. In our presentation we will proceed practically and theoretical discussions will be skipped, where it is possible The Repository The Repository is a concept that has been developed in the first version control systems. It is a matter of location 1 where all versions of the version controlled files are stored. If several persons want to work together on some files they may proceed as follows: 1. make a copy of the old file, which is to be changed 2. make the changes in the copy 3. tell all others that the copy is the new version Practically, this is a simple ( but manual ) version control system. For not making all the work by hand there are software systems available which do exactly this job. The most important thing to have for a version control system is a repository, which should be located on a secure computer. This computer should be integrated into a backup process and should be connect-able over the Internet. 1 In the world of computers a file, a directory, or database 27

28 4 Tools in Software Engineering A very good location for a repository in this lab is your personal home directory at the TU. Come to a compromise with your co-worker, where to create such a common repository for the lab, if in your home or in the home directory of your colleague is of secondary importance, you just have to fix one position for your common repository. Create a Subversion-Repository At first you should change to your personal home directory with the command cd Now you can create a new directory for placing the repository there. You may choose the name REPOS, just as we do in this tutorial: mkdir REPOS Now you can already initialise the repository with the subversion structure by using the command: svnadmin create REPOS This command creates an empty repository in the directory REPOS which contains the structure which subversion needs to provide its services. The content of this directory does not need to be investigated; changes by hand are taboo The working copy As discussed in the last section, manual changes to the repository are taboo. Now the question arises, how to use the repository at all. The answer is simple: you need to use subversion, because this program is responsible to manage data in the repository. Therefore subversion can create a working copy of the repository content; to create a working copy is often called to do a checkout. For creating a working copy you need again a directory where the copy shall be stored. Therefore you can create sub-directory in your home directory again. Let us call it WORK: mkdir WORK Now you should checkout a working copy by typing the command: svn checkout file://$pwd/repos WORK Here you use for the first time the user interface to subversion the program svn. The first parameter checkout is a command, that is interpreted by svn. The first parameter of the checkout-command is always a URL (Uniform Resource Locator), as you might know them from the Internet (e.g. Here you do not want to access a hypertext (as with http URLs) in the Internet, but a directory which is stored locally on the same machine on which you are working. Therefore you have to use the URL-scheme file. The Environment-variable $PWD, which has been used in the last call contains the absolute path of the current working directory. The last parameter WORK is 28

29 4.2 Version Control Subversion the relative path to the directory where subversion shall create the working copy. The answer which subversion should give after the last call 2 is: Checked out revision 0. Now you have a working copy of the current version in the repository in the directory WORK Working on a Working Copy Change at first into the directory of the working copy you have just created: cd WORK If you let the system list the content of the directory you will realise, that the directory is empty. If you think about it, it is no wonder, since you did not put yet anything into the repository. This we will change now: svn mkdir homework This command instructs subversion to create a sub-directory and to mark it to te be part of the next version. The last call is equivalent to the following two: mkdir homework svn add homework The difference is obvious: the first call used svn to create the directory homework and svn marked the directory automatically and the second variant created the directory without using subversion and then marked the directory explicitly with the subversion command add. Both calls are functional equivalent and produce the same result. Creating Versions It is important to understand that not every change in the working copy changes the version in the repository. Subversion is a version management system, therefore you have to tell it explicitly, when you exact a state of the files to be a new version. This is to be done with the commit command of subversion. We have just created the directory homework and we have marked it to enter the new version. If you would like to apply the changes and make the repository aware of the new version, you shall type: svn commit -m Directory homework created which commits the current state of the working copy to be the new version. The text Directory homework created after the commit parameter -m is the message which finds its way to the logbook of the repository. The log message shall contain enough 2 If the language of the command line is put to Java see chapter 2.2.2). 29

30 4 Tools in Software Engineering information to explain yourself or other members in the team; what changes you made with this new version. Subversion answers to this call by printing: Adding homework Committed revision 1. The repository contains now the new version. Subversion Commands You can get a list of available commands which svn supports with the svn command help: svn help There you can also find the commands you have already used, but you can also see other commands which you already know from the UNIX command line (e.g. mkdir, ls, rm, cp). There are also commands, which may be new to you: add mark directory or file for inclusion into the version control remove unmark directory or file for inclusion into the version control diff shows the difference between a local file an the respective file in the repository status shows the state of the files and directories of the working copy commit sends the current state into the repository to define a new version update updates the working copy to the state in the repository A Repository with multiple users Version control gets more interesting if more than one people work together which have their own working copy each. Then there are potentially multiple concurrent versions of the common files. We consider the example that you want to work on the exercises at in the courses and home on your private computer. Therefore you have to create a second working copy on your private machine. Working copy from the Internet Discover the Internet address of your repository In the last sections you created a subversion repository in your home directory at the Gauß-IT-Centre. To access this repository from your computer at home you have to remember the location of the repository in the TU file system. The path of your home directory you get by typing 30

31 4.2 Version Control Subversion echo $HOME The command echo svn+ssh://rzlx0005.rz.tu-bs.de/$home/repos now gives you the URL of your repository. This URL you can use as parameter for the svn command checkout (as shown in section 4.2.2) from everywhere of the world. The access to the repository is saved by your personal password. Working with the AFS and subversion at the TU Your Repository is saved on storage in the TU file system. If you want to provide someone else access to the created repository (someone as your college in this course), you have to allow his user-name the access to the repository. This you can do with: find REPOS -type d -exec fs setacl USER rlwikd \; This maybe looks look a little bit complicated, but it adds the user name USER to the access control list of all sub-directories of the repository with the name REPOS. For changing recursively the access control list of every sub-directory the find command is used which executes the command after its parameter -exec for all entities find found. The command fs setacl meaning file-system set access control list adds the user with the user-name USER to all entities () find discovers (that are all directories therefore the -d) the right rlwikd. Rights management TUs file-system are explained on After this command, your colleague has access to the repository Multiple Working Copies, Conflicts and their resolution When you use SVN extensively you will reach the point that two different version of the same file are concurrently in existence. The first commit defining the new version will complete without error, but a second commit of the other file will create a conflict, because there are two different versions trying to become the new one. In this situation subversion can nor automatically decide, what you want it to do. Therefore it prints out an error and asks you to resolve the conflict. For supporting you in the resolution, Subversion creates files with each of the versions which are competing. To resolve the such errors is out of the scope of this text. In the context of this course it is very unlikely to have such problems. The resolution is not complicated an described e.g. here: 31