CS/CE 218 Lecture -*- Outline -*-

Connection: Functions are an important modularity tool in C programming.
Now we'll look a second tool: separate compilation of code contained in
different files.

* separate-compilation

Advert: Separate compilation is a feature of C that makes it far better than
Pascal for large programs.  We'll look at the basics of dividing up your
program into separate files today, and see how to get the parts to communicate.

** Compiler options (Unix book, section 14.1)

*** compile and link
	Compilation turns C into object code (by way of assembler)
	Linking makes all the functions and data in your program work together,
		tells each function where the other functions are

	Suppose have a file roman.c
#include <stdio.h>

#define ROWS	4
/*...*/

int pows[ROWS][COLS] = {  /*...*/ };

int main(int argc, char *argv[])
{
  extern void checknum(int);
  extern void to_roman(int, char []);
  int low;
  char roman[25];
  /*...*/
  checknum(low)
  /*...*/
  to_roman(low, roman);
}

void checknum(int value)
{
  /* ...fprintf(...) ...*/
}

void to_roman(int decimal,
	      char roman[])
{
  /*... ROWS ...*/
}

	Q: How do you compile and link a program, all contained in ``roman.c''?
		gcc roman.c
			produces file a.out
		gcc -o roman roman.c
			produces file roman
		note gcc -O roman.c
			produces optimized version of a.out

*** saving results of file compilation
	Q: Why would you want to save the results of compiling a single file?
		so when make a mistake don't have to recompile everything...
		cf. Pascal philosophy

	Imagine each of the functions in separate files

	roman.c
-----------------
#include <stdio.h>

#define ROWS	4
/*...*/

int pows[ROWS][COLS] = {  /*...*/ };

int main(int argc, char *argv[])
{
  extern void checknum(int);
  extern void to_roman(int, char []);
  int low;
  char roman[25];
  /*...*/
  checknum(low)
  /*...*/
  to_roman(low, roman);
}
-------------------

	checknum.c
-----------------
#include <stdio.h>

void checknum(int value)
{
  /* ...fprintf(...) ...*/
}
------------------

	to_roman.c
-----------------
#define ROWS	4
/*...*/

extern int pows[ROWS][COLS];

void to_roman(int decimal,
	      char roman[])
{
  /*... ROWS ...*/
}
------------------

	Q: How do you compile checknum.c to get an object file?
		gcc -c checknum.c
			produces checknum.o
		gcc -c *.c
			produces checknum.o roman.o to_roman.o

	Q: What happens if you execute ``gcc roman.c'', where roman.c
		is the file with the main program?

		you get an error from the linker (ld),
			that the symbols checknum and to_roman are undefined.

		if you compile gcc to_roman.c, get an error because _main
			is not defined.
*** linking
	process that brings together separately compiled files
		into an executable 
			(resolves external references)
	You can use ld
		but best to use gcc (or cc)

	Q: How do you use gcc to do link roman.o, checknum.o, to_roman.o?
		gcc -o roman *.o
			produces executable roman
		gcc *.o
			produces executable a.out

	Q: Suppose you use the square root routine from the math library,
		how do you tell ld or gcc to link with that library?
		gcc -o roman *.o -lm

	-lm gets library /lib/libm.a
	-lc gets library /lib/libc.a
	-lFOO gets library /lib/libFOO.a

** external variables are visible across files (section 4.3 in C book)
	(draw picture)
	Q: What does external mean?  What does internal mean?
		names may be defined within or outside a function
		function names always external

	Q: How do you get the effect of a Pascal global variable in C?
		external variables

	An automatic variable is local to a function,
		space allocated on each entry

	Q: What properties distinguish external variables from automatic vars?
		external has greater scope (larger area of program)
		external has longer lifetime (permanent)

	Good to use external variables if 2 functions share the same data,
		yet neither calls the other
		(gee, this is an ADT)


*** an example (in the book, see pages 75-79)
	This example different from the book's
		it's from a shell pre-processer
	
	Idea: copy file to standard output, replacing lines of the form
 		includeonce(filename) with the text of the included file name.
	The string "includeonce(" must appear in as first characters
	of the line to be recognized.  Includes can be nested.  Files are only
	replaced the first time they are included.

	e.g., if cmd.sh contains
		includeonce(args-required.sh)
		includeonce(cmd-body.sh)
	and args-required.sh contains
		if test $# -eq 0
		then
			echo "$USAGE" >&2
			exit 1
		fi
	and cmd-body.sh contains
		includeonce(args-required.sh)
		echo $2 $1
	then shpp <cmd.sh outputs
		if test $# -eq 0
		then
			echo "$USAGE" >&2
			exit 1
		fi
		echo $2 $1

	psuedo-code:
		while (not end of file)
			if line doesn't start with "includeonce("
				copy it to stdout
			else /* the line does start with includeonce( */
				if it has been included
					ignore it
				else
					open the file and do all this (recurse)
					record the file as included

	The ADT here is the "string_set"
		operations
			void string_set_insert(char [])
			int string_set_has(char [])

	To do the recursion need structure as follows
		/* #includes */
		/* #defines */
		extern void shpp(FILE *);
		main()
		{
		   /* ... */
		   shpp(stdin);
		}

		/* string_set external variables */
		void string_set_insert(char [])
		{ /* ... */ }
		int string_set_has(char [])
		{ /* ... */ }

		void shpp(FILE *fp)
		{
		  /*... string_set_has(buf) ...*/
		}

	Look at the specification of the string set ops:
		void string_set_insert(char s[])
		     /* EFFECT: put a copy of s in the set */
		int string_set_has(char s[])
		     /* EFFECT: is s in the set? */
		how is the set created?  When program starts it's empty.

	Decide how to represent the set
		use an array of strings, keep track of how many in the array
		ensure that no duplicates get in the array

#define MAX_TRACKED_INCLUDES 1000
#define MAX_PATHNAME_LENGTH 500

char already_included[MAX_TRACKED_INCLUDES]
		     [MAX_PATHNAME_LENGTH];
int num_tracked = 0;

	Note that these are *external* variables!
	Also note initialization of num_tracked

	Write the code:

void string_set_insert(char s[])
   /* EFFECT: put a copy of s in the set */
{
  int i;
  for (i=0; i<num_tracked; i++) {
    if (strcmp(s,already_included[i]) == 0) {
      return;
    }
  }
  strcpy(already_included[num_tracked], s);
  num_tracked++;
}

int string_set_has(char s[])
   /* EFFECT: is s in the set? */
{
  int i;
  for (i=0; i<num_tracked; i++) {
    if (strcmp(s,already_included[i]) == 0) {
      return(1);
    }
  }
  return(0);
}


** scope rules (section 4.4)
	scope = area of program text where declaration has effect
	The book says that scope is a property of a name,
		really it's a property of a declaration (or definition)
		e.g., z may be declared in different functions,
			but the scope of each declaration is only 1 function

*** scopes of declarations: file and (remainder of) function, blocks
	Q: Does the scope of a declaration include text before 
		that declaration? 
		no, only goes down the page...

	no declaration has scope that extends beyond a file
		(but using exports and imports
		there is a way to share definitions among files)

	scope is remainder of file:
		declarations outside any function (including functions)

	Q: Can already_included be used in main below:
		main()
		{
		  /* ... */
		}
		char already_included[500][100];
		string_set_has(char s[])
		{
		  /* ... */
		}
	    Can it be used in string_set_has?

	local to a function:
		declarations within body of function
			as in Pascal

	local to a block:
		decl within a block (e.g., { int x; ...})
			extension of the above


*** definition vs. declaration
	Q: What's the difference between a definition and a declaration?
	Q: Is ``extern int x;'' a definition or a declaration?

	a definition allocates storage, or provides an implementation of a fun
			(called an object in the reference manual)
		int x;
		foo(x) { return(x+1); }
	a declaration describes attributes
		extern int x;
		extern int foo();
	every definition is a declaration, but not vice versa.
		int x;
		is a definition, also serves as a declaration
			so can't say int x; extern int x;

	Q: How many definitions of an external variable are permitted?  Why?
		1, prevents inconsistencies

	example:
		file string_set.c (these are definitions!)
			void string_set_insert(char [])
			{ /* ... */ }
			int string_set_has(char [])
			{ /* ... */ }
		file shpp.c contains:
			extern void string_set_insert(char []);
			extern int string_set_has(char []);

*** block structure (section 4.8)
	a local declaration hides more global declaration
		useful if global declaration is in a header file but not used

	Q: What ways can a declaration hide a declaration in a surrounding
		scope?
		declared in a block
		declared as a parameter to a function
		declared as an auto var of a function
	Q: Is it a good idea to hide declarations in outer scopes?

		no

	C is a block structured language
	saw a use of this already, in reclaiming storage
	Unlike Pascal, functions don't nest in C
			but can make declarations and defs within a { } pair

** lifetimes: (storage classes, extent)
	in Pascal have no control over how long a variable is accessible
		other than making it more global;
		so can't separate lifetime from scope
	in C can separately describe a variable's lifetime
*** infinite = whole program's execution (called static extent)
		both extern and static
			-initialized when program starts running
				(if have initializer, 0 otherwise)
			-only one instance (object)
			-default for functions and defs outside functions
				(i.e., extern definitions)
		static variables are a way to get this lifetime with more
			limited scope
			(e.g., seed in random number generator)

*** limited to activation of a function (called auto)
		allocated on the run-time stack
			-more than one instance if have recursion
			*can be placed in registers!
			-default for function and block locals, and
			 register vars

*** initialization (section 4.9)
	Unlike Pascal, variables can be initialized in their definitions
		e.g., int x = 3;
			double pi = 3.14, e = 2.73;
	Initialization is especially important for
		consts (const double pi = 3.14159)
		and vars with static extent (static int seed = 64954)

	How to initialize variables
	Q: If an external variable is not initialized explicitly, can you
		assume it has some particular value?
		yes, 0 (has static extent)
	Q: Can initializer of an external variable involve a function call?
		no, must be a constant expression
			because need to know value before running program.
	Q: Can initializer of an auto variable involve a function call?
		yes

	Q: Should you use initialized declarations?
		depends; make program easier to read...

	Q: How do you initialize an array?
		char includeonly[] = { 'i', 'n', 'c', /*... */ , '\0' };
	can shorten this to 
		char includeonly[] = "includeonly(";
		which includes the implicit '\0' character

** preprocessor
	purely textual substitutions of defined text for macro name
		helps avoid repeating text (e.g., extern decls)
*** header files, typically named *.h (section 4.5)
	a header file only has #define, #include and extern declarations
		(a lie but almost true)
	Q: What is the advantage of using header files?
		want to avoid repitition of declarations used by many files
	Q: When should you use more than one header file per program?
		when the program gets big
		when separate subsystems may be reused independently
			group stuff by function (ADTs)

	in file string_set.h:
extern void string_set_insert(char []);
extern int string_set_has(char []);

	in file shpp.c:
#include "string_set.h"

*** file inclusion (section 4.11.1)
	One of the tasks of the preprocessor is to include the text of files,
		either from a standard place or by path name

	Q: What is the difference between #include "file.h"
		and #include <file.h>?
		"file.h" search *starts* in current directory
		<file.h> search does not include current directory
			usually found in standard place /usr/include

	can add more standard places:
		gcc -I$HOME/include file.c

	Q: If a header file is changed, what do you have to recompile?
		files that include it.
	Q: Can you compile a header file?
		no (doesn't make sense, it's a part of another file,
			compiler doesn't recognize .h suffix)

*** macro substitution (section 4.11.2)
	--------------
	#define TRUE 1
	#define FALSE 0
	--------------
	Q: What are the parts of a macro definition?
		name, and replacement text

	Q: Can the repolacement text take up more than one line?
		only if continue with backslash \

	Q: What are some pitfalls in defining macros?
		need to enclose args in parentheses
			#define add(A, B) A + B
			3 * add(5, 6)  ==> 3 * 5 + 6
		each use of parameter replaced by argument text (not value!)
			#define min(A, B) ((A) > (B) ? (A) : (B))
			causes problems if arguments have side effects
			min(i++, 4) ==> ((i++) > (4) ? (i++) : (4))

	Q: What are some advantages of macros over functions?
		polymorphism, works for any type of argument
		reduces run-time overhead for very short functions

	Q: Can you do exercise 4-14?

*** conditional inclusion (section 4.11.3)
	helps to make code portable (!)
	also commonly used to make sure header files are only included once...

	Q: How do you ensure that a header file is only included once in C?
	#if !defined(MYFILE_H)
	#define MYFILE_H
		/* ... */
	#endif