Notes on Makefile and More - CSCI 531, Spring 2016


Notes on Makefile and More - CSCI 531, Spring 2016
You are suppose to know how to write a `Makefile` already. If you don't, you should learn it as soon as possible because your `Makefile` must work in all your project submissions. There are a few tutorials on `make` on the web. Here are links to some of them. I have not really read through these pages so I cannot guarantee their correctness. a detailed tutorial from University of Hawaii a one-page tutorial from Indiana University a one-page tutorial from Rutgers University etc.

Windows Makefiles
Please be aware that if you transfer a `Makefile` from a Windows environment to a UNIX environment, chances are, it will not work. The reason is that a line in a text file in Windows ends with "\r\n" while a line in a text file in UNIX ends with just "\n". The extra "\r" can confuse `make` on UNIX machines. But I'm sure you can write a small program to fix that.

Compiling Your Code
If you are writing your program in C, you should use `gcc` as your compiler, rather than `cc`. `Gcc` supports function prototypes and other ANSI extensions, which you should use in your programs. The option `-Wall` turns on most of the useful `gcc/g++` warnings. Compiling with this option will find many simple mistakes in your programs. On many platforms you also need to link the network and socket libraries to your program.

Compilation Requirements
We will evaluate your submission by copying all the files you have submitted into an empty directory and then type the following command: make (If an individual project spec has more specific way of producing executables, you must follow it.) Minor variation (such as using `gmake`) is allowed, but you must describe in details how to compile your code near the top of your README file. Requiring a visual tool to compile your code is not allowed. If this does not produce the desired executable(s), you will probably lose a lot of points. You may lose quite a few points if the grader has to debug and modify your Makefile in order to get your code to compile. How many points you will lose depends on how hard it is for the grader to get your Makefile to work. You may even receive a score of zero if we cannot get your Makefile to work. Here are some additional requirements: You are required to use separate compilation to compile your source code. You must divide your source code into separate source files in a logical way. Even if everything can fit in a single source file, you must force yourself to cut it up or you will lose a lot of points! You must not put the bulk of your code in header files! Header files are not where you are suppose to put your source code because you will lose the ability to debug your code. When the following command is invoked at the UNIX prompt: make clean all binary files created during compilation (.o files, .gch files, executable files, etc.) must be removed. You must use `-Wall` (or equivalent) in your Makefile when you compile with `gcc/g++` and you must eliminate all compile-time warning messages. By the way, if you think you have a perfectly working Makefile but when you run "make", you get an error message saying it does not know how to make a target, it's probably because you have created or modified your Makefile on a Windows machine and what you have is a DOS/Windows text file, which is not quite compatible with a Unix text file. In this case, you can either use "`gmake`" or run "`dos2unix`" to convert a DOS/Windows text file into a Unix text file. When you compile, if you get warning messages saying that certain `.c` or `.h` file has no newline at end of file, then it's cause by the same problem (i.e., you have created these files in Windows). Please run "`dos2unix`" to convert such a DOS/Windows text file into a Unix text file.

README Requirements
[BC: section updated 1/24/2016] The README file you submit must not be empty. Here are things that you should consider putting in it: Any design decisions you made that is not in the spec. This is not required. (Some people likes to document their code so that when they look at their code 5 years later, they can easily figure out what they have done.) Known bugs (not required, but it's nice to have so the grader knows what to expect). Tests or sections in the "plus points" section of the grading guidelines to skip (not required, but it may be a good idea to have if you have cases where you know for sure that running them will cause segmentation faults and you try not to lose additional points in the "minus points" section). Any deviation from the spec (e.g., minor variation on "make" may not lost points, minor variation on others may lose points). References and credits (e.g., you use some code you find on a web site if the spec permits it). You do not have to repeat anything from the spec in your README file. But if you want to (so that you have a self-contained document), please mark it clearly so the grader can easily skip such description. If you think that your submission will get a perfect score, all you have to do is to declare that it works perfectly according to spec and grading guidelines and you don't have to say anytning else!

Citation Requirements
For programming assignments where you are permitted to use code fragments obtained from public sources (or code derived or adapted from them), you must explicitly cite from where you obtained the code, and you must use the correct procedure to cite your source. You must read the licensing terms of the public code carefully before you start using the code. You must comply with the licensing terms of the code if you decide to use it in your assignment. If the licensing terms of the code says that you must include certain copyright notice in your code, you must do so. If you are only copying some functionalities from a public source, as soon as you have copied them into your code, do the following immediately. Surround the downloaded code with a comment above and a comment below. The comment above should say something like the following (please adapt it for your case): /* * Begin code I did not write. * The following code was obtained from <URL>... * [ copyright so and so, if required ... ] / The comment below should say: / * End code I did not write. / With this declaration, you would be saying that you wrote everything else yourself. Although it's a good idea to summarize* what code you have used in your README file, just saying that I use code from this and that URL in your README file is not an acceptable way of giving citation. You must also cite your source using the method described above. Please note that if a web site is accessible only if you provide user ID / password, then the code there is considered private code and you must not use it. Also, under no circumstances can you use code from previous semesters written by another student.

Additional Hints
How do you make sure that `make` would work? It's actually very simple. Create a `Makefile` first time you need to compile your code. Don't wait till the last minute. If you do your development on Windows and expect your code to just compile and run on nunki.usc.edu, you will soon find out how unrealistic your assumption is. I would leave at least 2 days for porting for small projects and 5 days for porting large projects. Write a rule in your `Makefile` to generate a submittable file in the right format. Do this early! You can also think of this as generating a backup copy of what you have done so far. Copy the backup copy to another place in case you accidentically erase all your files. Testing! Verify your submissions. Create an empty directory on nunki.usc.edu, unpack your test submission, and type `make` in it! If it doesn't work, fix it right away. Have a working copy ready for submission. When it's 2 hours away from the deadline and your code is not completing working, you should probably consider doing the following. Fix your code so that it compiles and runs. Create a submission from your working code and keep it as a backup in case you can't fix your bugs when deadline comes. Repeat this as you fix more bugs.