Importing a C function

Question

What's wrong with the following import statement? I feel like I'm screwing up something pretty basic here:

// main.c
#include <stdio.h>
#include "1_square.h"

int main(int argc, char *argv[]) {
    int a=4;
    int a_squared=square(a);
    printf("Square of %d is %d\n", a, a_squared);
    return 0;
}

// 1_square.h
int square(int num);

// 1_square.c
int square(int num) {
    return num*num;
}

$ gcc 0_main.c -o 0_main && ./0_main

/usr/bin/ld: /tmp/cc6qVzAM.o: in function main': 0_main.c:(.text+0x20): undefined reference to square' collect2: error: ld returned 1 exit status

Or does gcc need a reference to 1_square in order to build it?

Answer 1

You need to add the 1_square.c file to your build command:

gcc -o 0_main 0_main.c 1_square.c && ./0_main

You need the definition of the function as well as its declaration.

From the comments:

Why then does it need 1_square.c in the commandline and then also 1_square.h in the 0_main.c header?

Like John Bollinger points out in the comments, the only thing 1_square.h and 1_square.c have in common is their name, which isn't meaningful to the compiler. There's no inherent relationship between them as far as gcc is concerned.

Let's start by putting everything in one source file:

/** main.c */
#include <stdio.h>

int square( int num );

int main( int argc, char **argv )
{
  int a = 4;
  int a_squared = square( a );
  printf( "Square of %d is %d\n", a, a_squared );
  return 0;
}

int square( int num )
{
  return num * num;
}

In C, a function must be declared before it is called in the source code; the declaration introduces the function name, its return type, and the number and types of its arguments. This will let the compiler verify that the function call is written correctly during translation and issue a diagnostic if it isn't, rather than waiting until runtime to throw an error. In this particular case, we specify that the square function takes a single int parameter and returns an int value.

This says nothing about the square function itself or how it operates - that's provided by the definition of the square function later on.

A function definition also serves as a declaration; if both the caller and called function are in the same translation unit (source file), then you can put the definition before the call and not have to mess with a separate declaration at all:

/** main.c */
#include <stdio.h>

int square( int num )
{
  return num * num;
}

int main( int argc, char **argv )
{
  int a = 4;
  int a_squared = square( a );
  printf( "Square of %d is %d\n", a, a_squared );
  return 0;
}

This is actually preferable as you don't have to update the function signature in two different places. It means your code reads "backwards", but honestly it's a better way to do it.

However, if you separate your function out into a separate source file, then you need to have a separate declaration:

/** main.c */
#include <stdio.h>

int square( int num );

int main( int argc, char **argv )
{
  int a = 4;
  int a_squared = square( a );
  printf( "Square of %d is %d\n", a, a_squared );
  return 0;
}

/** square.c */
int square( int num )
{
  return num * num;
}

When it's processing main.c, the compiler doesn't know anything about the definition of the square function in square.c - it doesn't even know the file exists. It doesn't matter if main.c is compiled before square.c or vice-versa; the compiler operates on one file at a time. The only thing the compiler knows about the square function is that declaration in main.c.

Having to manually add a declaration for every function defined in the separate .c file is a pain, though - you wouldn't want to write a separate declaration for printf, scanf, fopen, etc. So BY CONVENTION we create a separate .h file with the same name as the .c file to store the declarations:

/** main.c */
#include <stdio.h>
#include "square.h"

int main( int argc, char **argv )
{
  int a = 4;
  int a_squared = square( a );
  printf( "Square of %d is %d\n", a, a_squared );
  return 0;
}

/** square.h */
int square( int num );

/** square.c */
int square( int num )
{
  return num * num;
}

By convention, we also add include guards to the .h file - this keeps the contents of the file from being processed more than once per translation unit, which can happen if you #include "square.h" and include another header which also includes square.h.

/** square.h */
#ifndef SQUARE_H       // the contents of this file will only be
#define SQUARE_H       // processed if this symbol hasn't been defined

int square( int num );

#endif

Also by convention, we include the .h file in the .c file to make sure our declarations line up with our definitions - if they don't, the compiler will complain:

/** square.c */
#include "square.h"

int square( int num )
{
  return num*num;
}

After both main.c and square.c have been compiled, their object code will be linked into a single executable:

main.c ------+-----> compiler ---> main.o ----+--> linker ---> main
             |                                |
square.h ----+                                |
             |                                |
square.c ----+-----> compiler ---> square.o --+

We must compile both C files and link their object code together to have a working program. No doubt your IDE makes this easy - you just add source files to the project and it builds them correctly. gcc lets you do it all in one command, but you must list all the .c files in the project.

If you're running from the command line, you can use the make utility to simplify things. You'll need to create a Makefile that looks something like this:

CC=gcc
CFLAGS=-std=c11 -pedantic -Wall -Werror
main: main.o square.o
all: main
clean:
        rm -rf main *.o

All you need to do then is type make at the command line and it will build your project, using built-in rules for compiling main.c and square.c.