Learning goals

You will learn the following concepts/skills:

1. C preprocessor − how to use several of the most commonly used directives
   1. #define symbols – not just for defining constants
   2. #define macros – like functions but with special capabilities
   3. #ifdef/#ifndef – disable sections of code with a #define or GCC flag
   4. #include guards – enable more versatile use of header (.h) files.
2. ANSI color codes – Print text in color on the terminal

Overview of the Miniunit series (HW06, HW07, HW08)

This assignment is part 1 of a 3-part series collectively referred to as miniunit.

Real-world software projects typically comprise tens, hundreds, or many thousands of files. Even in your ECE courses, your programming assignments will be getting bigger and more complex. Testing code by hand (i.e., by playing with it) is useless since there are so many components, and ways things can go wrong. Hand-testing effectively would be complex—and prohibitively slow.

Most serious software projects use two tools: a unit testing framework (e.g., CUnit) to organize and coordinate tests, and a build system (e.g., make) to manage the process of compiling, testing, and deploying the project. In this homework, you will get a light introduction to both. In addition, you will learn to use console logging effectively (as a complement to gdb), without littering your code with printf(…) statements.

In the Miniunit Series, you will create the following:

• clog.h – your own library for smarter printf-style debugging and logging. From now on, instead of debugging with printf(…) directly, you will use function-like macros to print values in various formats and colors to make the output easier to view. You will use preprocessor directives to ensure that your debugging code does not interfere with your tests, or show up inadvertently when others are testing your code.
• Makefile – input file for the make build system. You will be able to build, test, submit, and/or pre-test your code with one command from bash or directly from Vim (and other editors).
• miniunit.h – your own simple unit test library. You can use this to test future assignments in this class, or for any other project you do in C (or C++) beyond ECE 264. This consists of four #define macros that you can use in your test code. The most important macro you will create is mu_check(…), which is somewhat similar to assert(…).

Starter code

You will create your clog.h from scratch (i.e., starting with a blank file).

There is also a script called print256colors.sh (created by Tom Hale). It will not be used directly for the assignment, but running this script will give you some exposure to the range of colors your terminal can display.

Run 264get hw06 to fetch these files.

For HW06: clog.h

For this part, you will create a reusable library for debugging any C project. In the process, you will learn about the C preprocessor and ANSI control codes.

Instructions

#include <stdlib.h>
#include "clog.h"

int main(int argc, char* argv[]) {
  char* city_name = "Bogota";
  int population_pct = 15;
  logf_("%d%% of Columbians live in %s.\n", population_pct, city_name);
  return EXIT_SUCCESS;
}

#ifndef NDEBUG
    // Macros
    //▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
#else
    // DUMMY macros
    //▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
#endif

logf_red("%s\n", "RED");

log_int(3 + 4);
log_int(population_pct);

log_char('A');
log_char(65);
log_char(city_name[0]);

log_str(city_name);

log_addr(city_name);

log_float(1.0 / 8.0);

log_bool(3 > 5);
log_bool(3 > 1);

How much work is this?

Requirements

Submit

To submit HW06 from within your hw06 directory, type 264submit HW06 clog.h test_clog.c test_count_words.c

Pretester

Q&A

1. How do I use a variadic macro to pass arguments from logf_red(…) to printf(…)

   In the LHS of the #define, use “...” to indicate 1 or more arguments. In the RHS, use __VA_ARGS__ to pass those same arguments to the next function (e.g., printf(…)). Note that “...” stands for one or more, not zero or more.
   Here's a simple example:
   #define my_printf(...) printf(__VA_ARGS__)
   That macro would convert my_printf("%d", 3) to printf("%d", 3).

2. Should I have a semicolon at the end of the RHS of a #define macro

   No. The person using the macro will normally include the semicolon.

3. How can I continue the RHS of a #define macro definition onto the next line

   Put a backslash ("\") at the end of the line.

   #define profess_love_for_food(food) printf("I love %s", \
           food)

4. Can I have a macro with multiple C statements

   Yes. In theory, you could just have the two statements separated by a semicolon like this:

   // BAD
   #define profess_love_for_two_foods(food1, food2) \
         printf("I love %s", food1);                \
         printf("I love %s", food2)

   However, that would lead to surprising results if someone who doesn't follow the code quality standards calls that macro in an if statement like this:

   if(1 == 0)
       profess_love_for_two_foods("soap", "poison");

   Only the first statment would be connected to the if statement.

   if(1 == 0)
       printf("I love %s", "soap");
   
   printf("I love %s", "poison");

   It is tempting to just put curly braces around the two statements, but that also causes problems.

   // BAD
   #define profess_love_for_two_foods(food1, food2) { \
       printf("I love %s", food1); \
       printf("I love %s", food2); \
   }

   The problem comes back to uncivilized oafs who write if statements without curly braces, like this:

   if(age >= 30)
       profess_love_for_two_foods("chocolate", "pizza");
   else
       profess_love_for_two_foods("spinach", "broccoli");

   The above example would result in this:

   if(age >= 30) {
       printf("I love %s", "chocolate");
       printf("I love %s", "pizza");
   };  ← PROBLEM
   else {
       printf("I love %s", "spinach");
       printf("I love %s", "broccoli");
   };

   The standard solution is to wrap the statements in a do { … } while(false) block. Because the do…while requires a semicolon, this actually works out like we want.
   Yes, it is ugly. Hacks like this are not something the instructor would normally condone, but it is standard practice because there are very few truly versatile options for this.

   // USE THIS WAY
   #define profess_love_for_two_foods(food1, food2) do { \
       printf("I love %s", food1);                       \
       printf("I love %s", food2);                       \
   } while(false)

5. How do I convert the printf(…) statements in test_count_words.c to use log_int(…)

   Here is an unrelated example that prints the output of a function using printf(…).

   #include <stdio.h>
   #include <stdlib.h>
   
   int triple(int n) {
     return n * 3;
   }
   
   int main(int argc, char* argv[]) {
       // BAD (… or less good)
       printf("triple(5) == %d\n", triple(5));
       printf("triple(4) == %d\n", triple(4));
       printf("triple(3) == %d\n", triple(3));
       printf("triple(2) == %d\n", triple(2));
       printf("triple(1) == %d\n", triple(1));
   
       return EXIT_SUCCESS;
   }
   

   Here is the same example converted to use log_int(…).

   #include <stdio.h>
   #include <stdlib.h>
   #include "clog.h"
   
   int triple(int n) {
       return n * 3;
   }
   
   int main(int argc, char* argv[]) {
       // GOOD
       log_int(triple(5));
       log_int(triple(4));
       log_int(triple(3));
       log_int(triple(2));
       log_int(triple(1));
       // Advantages over raw printf(…)
       // ∙ Easy to "turn off" when it is time to submit your code.
       // ∙ Less duplication means fewer oppportunities for bugs.
   
       return EXIT_SUCCESS;
   }
   

   With log_int(…), you can print the expression itself, along with its value.

6. What does #x do in a #define macro

   It expands to the text of the expression, instead of its value. This is easiest to see if you test using the 264cpp (or /usr/bin/cpp) command.
   Here is an example, which uses the log_int(…) snippet given in the Requirements table.

   // demonstrate_hash.c
   #include <stdio.h>
   #include <stdlib.h>
   
   #define log_int(n) printf("%s == %d\n", (#n), (n))
   
   int main(int argc, char* argv[]) {
       log_int(3 + 3);
       return EXIT_SUCCESS;
   }
   

   If we process that with the preprocessor directly (instead of via gcc), we can see what it becomes. Note: 264cpp is just a shortcut for /usr/bin/cpp ▒▒▒ | indent -kr that also cleans up the output a bit to make it easier to read.
   you@ecegrid-thin1 ~/HW06 $ /usr/bin/cpp demonstrate_hash.c | indent -kr

   … int main(int argc, char* argv[]) { printf("%s == %d\n", ("3 + 3"), (3 + 3)); return 0; }
   Notice that the second argument to printf(…) is a string literal, "3 + 3"—the text of the argument that was passed to log_int(…). That is different from the third argument, which is the value of that parameter, 3 + 3 (= 6).

7. I'm confused about isatty(…) and/or how to omit the ANSI color codes when output is going to a file or another program. What should I do

   This will be a small part of the score. If it isn't working for you, get the other parts working before worrying about this.

8. Why is this even a requirement

   Vim (and other editors) can help you compile your code directly—i.e., without leaving your editor—and show you the output right in the editor. However, the color codes are not interpreted, resulting in a mess. More generally, this issue comes up in many programs that print in color (e.g., ls); not printing the ANSI codes to a non-terminal is standard behavior for command-line programs.

9. Why does logf_(…) end with an underscore (‘_’)? Is that a typo?

   It is not a typo. The trailing underscore is to avoid conflicting with the standard library function (…) (calculate logarithm on a floating point value). This is inspired by the naming convention in PEP 8 , the official style guide for Python.

10. GCC: “ISO C99 requires rest arguments to be used.” ⋯??

    In variadic macros (see Q1), the ... can stand for 1 or more arguments. If your logf_red(…) looks like #define logf_red(format, ...) ▒▒▒▒▒▒▒▒▒▒, it will likely work as long as you pass ≥2 arguments (e.g., logf_red("I like %d", 5)), but if you pass only a string (e.g., logf_red("orange sky")), then there are 0 arguments for the .... It needs ≥1. The solution for our purposes is to remove the first argument (format).

11. GCC: “error: ‘true’ undeclared” ⋯???
    GCC: “error: ‘false’ undeclared” ⋯??

    The true and false constants are defined in a standard header called stdbool.h; you need to include it (i.e., #include <stdbool.h>) in any file where you use them (e.g., clog.h). This was communicated in #8 of the Requirements table, as well as the Code Quality Standards, which have more about bool, true, and false.

12. GCC: “implicit declaration of function ‘isatty’” ⋯???
    GCC “‘STDOUT_FILENO’ undeclared” ⋯??

    The isatty(…) function and STDOUT_FILENO symbol are defined in a standard header called unistd.h you need to include it (i.e., #include <unistd.h>). This was communicated in #7 and #8 of the Requirements table.

13. CPP: "Unexpected EOF (end-of-file)" (or similar). Why?

    You probably have unmatched braces somewhere in your clog.h or miniunit.h. First, fix your indents. Many errors will become much easier to spot. Then, be sure to use 264cpp test_count_words.c or /usr/bin/cpp test_count_words.c | indent -kr or /usr/bin/cpp test_count_words.c -D NDEBUG | indent -kr for more readable output.

14. What else could be wrong with my clog.h?

    Be sure you have parenthesized the condition parameter. The rationale was covered in both sections' lectures. See the slides. Failure to follow this has caused many students' errors and incorrect behavior.

Updates