makefile
  main.cpp
  machine.h
  machine.cpp
  user.h
  user.cpp
  log.txt

The first phase of 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 log.txt through emacs. The log will eventually be submitted as part of the project.

1. Basic Documents. Find these documents using the course organizer:

   1. Unix/Emacs Hints
   2. FAQ
   3. C++ Coding Standards
   4. Submission and Assessment of Programming Assignments
   Familiarise yourself with these documents, so that you can use them as references when you need to know their details.

2. Establish your Course Portfolio by completeing Assignment 0.

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 proj0. Complete the rest of this assignment inside this subdirectory.

4. Set up Emacs. (This is part of Assignment 0, repeated here in case you missed it.) 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_dot_files/.emacs ~/
   cp -r ~cop3330p/emacs_dot_files/.lisp/ ~/
   

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

5. Begin Log. Use Emacs to create a text file named log.txt. Type the following information at the top of this file:

   COP 3330
   Project Log
   (Your Name)
   CS  Username: (Your CS Username - used for login to CS account)
   FSU Username: (Your BB Username - used for login to Blackboard)
   

   Save the file and exit emacs.

6. 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 and your "submit.sh" command.

7. Aliases. Follow the instructions in the Unix/Emacs hints to create the "e" alias for Emacs.

8. Continue Log. Use Emacs to re-open your file log.txt. Open a second ssh window, and through that window get into your proj0 directory. Then issue these Unix commands:

   ls -l ~/cop3330/proj0/
   ls -l ~/.bin
   more ~/.alias
   more ~/.emacs
   ls -l ~/.lisp
   

   Using your mouse, copy the results of each of these commands into your log (via the Emacs session in your other ssh window). Then save your log and exit Emacs. Now close out the second ssh window.

Phase 2 of this assignment assignment consists builds on the file skills exercised in phase 1, specifically on how to use the command-line compilers and the make utility. Document your completion of these steps by copy/paste the screen results into a file named log.txt through emacs.

9. Re-use directory. Work in the directory cop3330/proj0 that you created for the first part of the assignment.

10. Get Project Files. Copy all of the files in ~cop3330p/LIB/proj0/ into the proj0 directory by entering the command:

    cp ~cop3330p/LIB/proj0/* .
    

    Note that there are five C++ code 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. (Put the description in your log.)

11. 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 log.)

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

    clang++ -c -I.   user.cpp
    clang++ -c -I.   machine.cpp
    clang++ -c   -I. main.cpp
    clang++ -osoda.x main.o machine.o user.o
    

    (Note that clang++ 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 log.

    It is advisable not to type the rm command with the '*' character anywhere - it carries out what you type without mercy. Many people have lost a lot of files being careless with rm.

13. 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>     clang++ -c   -I. user.cpp
       
       
       <TAB>     clang++ -c   -I. machine.cpp
       
       
       <TAB>     clang++ -c   -I. main.cpp
       
       
       <TAB>     clang++ -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>     clang++ -c   -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/proj0]>make soda.x
       clang++ -c  -I. main.cpp
       clang++ -c  -I. user.cpp
       clang++ -c  -I. machine.cpp
       clang++ -o soda.x main.o user.o machine.o
       program1[~/cop3330/proj0]>
       

       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.

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

15. Submit Project. Submit the makefile, source code, and log using the project submit system:

    1. Copy the files ~cop3330p/LIB/scripts/submit.sh and ~cop3330p/LIB/proj0/deliverables.sh into proj0

    2. If you prefer, you can copy "submit.sh" into your .bin so that it becomes one of your custom commands, like "clean" and "c3330". Then you won't need to copy it again for each project. You will still need the project configuration file for each project.

    3. Change permissions of these files to 700 (executable) by entering the command chmod 700 *.sh.
    4. Enter the command submit.sh deliverables.sh
    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. Before the deadline, assignments may be re-submitted as many times as you like. The new submission is just copied over the old one.
    6. Enter the command submit.sh deliverables2.sh

    Warning: Submit scripts do not work on the program and linprog servers. Use shell to submit projects.

    7. Check your CS email 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.

About Submit Scripts. The submission process requires two things: (1) a submission engine that does the processing - gathering up the files, encoding them, and emailing them to the appropriate location. And (2) a configuration file that gives the details on what files are to be submitted, what the project name is, and what course should get the submission.

The submission engine is the same for all assignments and is named "submit.sh". If you care to, this file can be put in your .bin directory and made executable, effectively making "submit.sh" a command invokable anyhere in your login so that it will not require copying into various assignment directories.

The specifics for any given assignment are contained in the configuration file, required by submit.sh. The default name for the configuration file is "deliverables.sh". A submission configuration file should be supplied for each assignment.

Checking CS Email. It is important that you check your CS Email regularly - at least daily. This is the system that is used by the department for all sorts of important stuff, including messages from the Department Chair, messages from the advising staff, messages from the local chapter of ACM, and ... email on assignments in this class. There are three ways to check your CS Email.

1. Log in to shell and check with a command line mail client such as pine or elm.
2. Set up a webmail client (see the system group web pages).
3. Forward the email to another system by placing the forwarding address in a file named "~/.forward".