Homework1: Compiling and Submitting Assignments

Educational Objectives: After completing this assignment, the student should be able to do the following:

Operational Objectives: Create your CS account and submit documentation that you can create, build, and run multifile programs using Unix, Emacs, g++ and Make.

Deliverables: Use the script hw1submit.sh to turn in the following files: makefile, main.cpp, machine.h, machine.cpp, user.h, user.cpp, report.txt.

This assignment consists of a sequence of steps performed with a Unix login session. To document your completion of these steps, copy/paste the screen results into a file named report.txt through emacs. Then submit the asignment using the submit script process.

  1. Establish CS Account. If you have not obtained a CS account, do so now at http://system.cs.fsu.edu/ select "New User", and follow the instructions. Once you have your account established, go the URL cited above and familiarize yourself with the rules and facilities of the system. You are now officially a part of the CS user community, and as such you have both rights and responsibilities.

  2. Set up Emacs. Log into your account on shell and copy some Emacs setup files that will make Emacs behave reasonably with respect to your keyboard:

    cp ~cop3330p/.emacs .
    cp -r ~cop3330p/.lisp/ .
    

    These files are publicly readable, so no group membership is required to copy them.

  3. Organize Account. Log in to your CS account. In your home directory, create a directory named cop3330. From within this directory, create a subdirectory named hw1. Complete the rest of this assignment inside this subdirectory.

  4. Begin Report. Use Emacs to create a text file named report.txt. Type the following information at the top of this file:

    COP 3330 Fall 2009
    Homework Assignment 1
    (Your Name)
    CS  Username: (Your CS Username   - used for login to CS account)
    FSU Username: (Your ACNS Username - used for login to Blackboard)
    

  5. Get Project Files. Copy all of the files in ~cop3330p/fall09/hw1/ into the hw1 directory by entering the command:

    cp ~cop3330p/fall09/hw1/* .
    

    Note that there are five files now in your directory: two header files and three implementation files. Use Emacs to examine each of these files. Note the #include<> statements referring to other files in the directory. Describe the header file contents and the implementation file contents.

  6. Learn what the servers are and what they are for. Look on the system web site and find out which CS servers are available to you and what they are used for. In particular:

    1. What is the "program stack"?
    2. What is the "linprog stack"?
    3. Where can you log in to send email?
    (Answer these questions in your report.)

  7. Compile Project. Log in to one of the linprog machines and issue the following sequence of commands:

    g++ -c -Wall -Wextra -I. user.cpp
    g++ -c -Wall -Wextra -I. machine.cpp
    g++ -c -Wall -Wextra -I. main.cpp
    g++ -osoda.x main.o machine.o user.o
    
    (Note that g++ and make are not available on shell. You need to log in to linprog or program to access these tools.) Note that these commands compile three implementation files to object code, and then create an executable named "soda.x". Use ls -l to verify that you have the object code files and the executable. Now run the executable (by entering its name). Explore enough to be able to describe this simulation, and write your description in the report.

    Access the online man pages for g++ and enter in your report the function of each of the flags -c, -Wall, -Wextra, -I, and -o. Which of these takes an argument, and what is the argument used above? (Explain.)

    Before beginning the next step, erase the object and executable files:

    rm *.o
    rm *.x
    

    Be careful using rm. It carries out what you type without mercy.

  8. Create a Makefile. Now use the utility named make to simplify the compilation process for this project. Make is a program running on the Unix machines designed to read a file of compile commands (or other shell commands) and create and keep various targets up to date. The file read by make is called a makefile. The default name for a makefile is "makefile".

    1. Use Emacs to create a file named "makefile". Place the following header at the top of this file:
      # makefile for soda machine project
      # 
      # COP 3330 Assignment 1
      # (your name)
      #
      
      Note the use of '#' to indicate comments.
    2. Place the four compile commands in the file, as follows:
      ...
      # (your name)
      #
      
      
      <TAB>     g++ -c -Wall -Wextra -I. user.cpp
      
      
      <TAB>     g++ -c -Wall -Wextra -I. machine.cpp
      
      
      <TAB>     g++ -c -Wall -Wextra -I. main.cpp
      
      
      <TAB>     g++ -osoda.x main.o machine.o user.o
      
    3. Immediately above each compile command, place a target followed by a dependency list for the target. The target should be the expected result of the compile statement, followed by a colon, followed by the dependency list. The dependency list should be the files that are required for the target to be created. Example:
      ...
      machine.o: machine.h machine.cpp
      <TAB>     g++ -c -Wall -Wextra -I. machine.cpp
      ...
      
      The depency list is determined by the #include<> statements in the code file being compiled. (Don't include library files in the dependency list, just the files that are specific to the project.)
    4. Now enter the command make soda.x. You should see the following on screen:
      program1[~/cop3330/hw1]>make soda.x
      g++ -c -Wall -Wextra -I. main.cpp
      g++ -c -Wall -Wextra -I. user.cpp
      g++ -c -Wall -Wextra -I. machine.cpp
      g++ -o soda.x main.o user.o machine.o
      program1[~/cop3330/hw1]>
      
      and a check should show that the project has been completely compiled.
    5. Erase the executable (rm *.x) and re-issue the make command. Note that only one compile command is invoked, for the target soda.x.
    6. Erase all of the object code files (rm *.o). Issue the make command without arguments. Note that only the first target is created.
    7. Re-arrange the lines in the makefile so that the executable target (dependencies and compile command) is listed first. Erase all object code and issue the make command without arguments. Note that the desired executable target is created, along with the various object code files on which it depends.

  9. Complete Report. Make sure that all steps in this assignment are documented in the report file report.txt. When a question is asked, answer it in writing in the report. To document a sequence of commands, open the report with Emacs in another window and copy/paste screen output into the report.

  10. Submit Project. Submit the makefile, source code, and report using the project submit system:

    1. Copy the file ~cop3330p/fall09/hw1/hw1submit.sh into hw1
    2. Change permissions of this file to 700 (executable) by entering the command chmod 700 hw1submit.sh.
    3. Enter the command hw1submit.sh
    4. You should see something on screen as follows:
      yourname@shell:~/cop3330/hw1>hw1submit.sh
      Changing directory to ....
      Archiving...
      a makefile 1K
      a machine.h 2K
      a machine.cpp 3K
      a user.h 2K
      a user.cpp 3K
      a main.cpp 2K
      a report.txt 2K
      Sending mail...
      Cleaning up...
      yourname@shell:~/cop3330/hw1>
      

      Warning: Submit scripts do not work on the program and linprog servers. Use shell to submit projects. If you attempt this on program, you will get a response like this:

      yourname@program1:~/cop3330/hw1>hw1submit.sh
      Changing directory to ....
      Archiving...
      a makefile 1K
      a machine.h 2K
      a machine.cpp 3K
      a user.h 2K
      a user.cpp 3K
      a main.cpp 2K
      a report.txt 2K
      elm: command not found
      Cleaning up...
      yourname@program1:~/cop3330/hw1>
      

      Note that "elm: command not found" implies that mail is not sent!

    5. Check your CS email (from shell) to verify that you receive two automatic responses to the submit:
      1. An email acknowledging receipt of the submission.
      2. An email containing the contents of what was received.
      Be sure that these agree with what you thought was submitted, and correct if necessary. Items may be re-submitted as many times as you like. The new submission is just copied over the old one.

  11. Optional Unix Command Scripts. After you have completed the required portion of this assignment, you may want to learn how to create a few time-saving (and mistake-preventing) Unix command scripts.

    1. From your home directory, get into the directory named ".bin"; create it if necessary.
    2. Using Emacs, create a file named "clean" with the following contents:
      #!/bin/sh
      rm $1/*.o
      rm $1/*.x
      
    3. Change the permissions on clean to 700 (owner executable) by entering the command:
      chmod 700 clean
      
    4. On your next login, you should now have the command clean that takes one argument, the name of the directory you want to clean up by removing object and executable files. The command is most often invoked in the current directory, as:
      clean .
      
    5. You can follow this model to create other convenience commands, such as shorthand compile commands.