Programas en varios archivos

1. Por qué dividir un programa

Un archivo de varios miles de líneas es difícil de leer, de navegar y de modificar sin romper algo. Dividirlo tiene ventajas que van más allá del orden:

• Compilación más rápida. Como vimos en el tema 4, al cambiar un archivo solo hay que recompilar ese archivo y volver a enlazar. Es la base de make, de los temas 35 y 36.
• Separación de responsabilidades. Cada archivo se ocupa de una cosa: formatear tamaños, mostrar mensajes, leer la configuración. Para entender una parte no hace falta leer las demás.
• Interfaces claras. Cada módulo expone unas pocas funciones y esconde el resto. Los demás módulos dependen solo de lo expuesto, y la implementación puede cambiar sin afectarlos.
• Reutilización. Un módulo bien separado se puede usar en otro programa, o convertirse en una biblioteca, como veremos en el bloque 8.
• Trabajo en equipo. Varias personas pueden trabajar en archivos distintos sin pisarse.

2. Un módulo: interfaz e implementación

En C, la unidad de organización es el módulo: un par de archivos con el mismo nombre.

Es la misma división que ya conocemos de la biblioteca de C: stdio.h es la interfaz, que incluimos en cada programa, y su implementación está compilada dentro de libc.so.6, como vimos en el tema 3. Quien usa printf lee su prototipo y su manual, nunca su código. La meta de un buen módulo propio es la misma: que quien lo usa solo necesite leer el .h.

3. El proyecto de ejemplo

Para todo el tema usaremos una pequeña herramienta, tamano, que muestra el tamaño de los archivos que recibe, en un formato legible. Reúne piezas de temas anteriores en tres módulos:

$ find . -type f | sort
./include/avisos.h
./include/formato.h
./src/avisos.c
./src/formato.c
./src/main.c

El módulo formato convierte bytes en texto, como tamano.c del tema 11, pero escribiendo en un buffer del llamador, la solución recomendada en el tema 12:

/* formato.h — convertir cantidades en texto legible */
#ifndef FORMATO_H
#define FORMATO_H

#include <stddef.h>            /* size_t */

/* Escribe en destino (de tam bytes) un tamaño como "15.6 KiB".
   Devuelve destino. */
char *formato_tamano(double bytes, char *destino, size_t tam);

#endif

/* formato.c — implementación de formato.h */
#include <stdio.h>
#include "formato.h"

static const char *unidades[] = {"B", "KiB", "MiB", "GiB", "TiB"};

char *formato_tamano(double bytes, char *destino, size_t tam)
{
    int i = 0;

    while (bytes >= 1024 && i < 4) {
        bytes /= 1024;
        i++;
    }
    snprintf(destino, tam, "%.1f %s", bytes, unidades[i]);
    return destino;
}

El módulo avisos es la función de mensajes del tema 11, convertida en módulo, con una variable compartida que decide si se muestran los mensajes informativos:

/* avisos.h — mensajes de la herramienta por stderr */
#ifndef AVISOS_H
#define AVISOS_H

extern int avisos_detalle;     /* 0: solo errores; 1: también información */

void avisos_iniciar(const char *nombre_programa);

__attribute__((format(printf, 1, 2)))
void avisos_error(const char *formato, ...);

__attribute__((format(printf, 1, 2)))
void avisos_info(const char *formato, ...);

#endif

/* avisos.c — implementación de avisos.h */
#include <stdio.h>
#include <stdarg.h>
#include "avisos.h"

int avisos_detalle = 0;                    /* la definición: aquí vive */

static const char *programa = "?";        /* privada de este archivo */

static void emitir(const char *tipo, const char *formato, va_list args)
{
    fprintf(stderr, "%s: %s", programa, tipo);
    vfprintf(stderr, formato, args);
    fputc('\n', stderr);
}

void avisos_iniciar(const char *nombre_programa)
{
    programa = nombre_programa;
}

void avisos_error(const char *formato, ...)
{
    va_list args;

    va_start(args, formato);
    emitir("error: ", formato, args);
    va_end(args);
}

void avisos_info(const char *formato, ...)
{
    va_list args;

    if (!avisos_detalle)
        return;
    va_start(args, formato);
    emitir("", formato, args);
    va_end(args);
}

Y main.c usa los dos módulos sin saber cómo están hechos:

/* main.c — tamano: muestra el tamaño de los archivos indicados */
#define _POSIX_C_SOURCE 200809L
#include <stdio.h>
#include <string.h>
#include <sys/stat.h>
#include "avisos.h"
#include "formato.h"

int main(int argc, char *argv[])
{
    int errores = 0;
    int primero = 1;
    char texto[32];

    avisos_iniciar("tamano");
    if (argc > 1 && strcmp(argv[1], "-v") == 0) {
        avisos_detalle = 1;
        primero = 2;
    }
    for (int i = primero; i < argc; i++) {
        struct stat info;

        avisos_info("consultando %s", argv[i]);
        if (stat(argv[i], &info) != 0) {
            avisos_error("no se puede consultar '%s'", argv[i]);
            errores++;
            continue;
        }
        printf("%10s  %s\n", formato_tamano((double) info.st_size, texto, sizeof texto), argv[i]);
    }
    return errores > 0;
}

4. Compilar el proyecto

Cada .c se compila por separado hasta su objeto, y al final se enlazan, como en el tema 4. La novedad es -I include, que agrega el directorio include a la lista donde el preprocesador busca los encabezados:

$ gcc -std=c17 -Wall -Wextra -Iinclude -c src/formato.c -o formato.o
$ gcc -std=c17 -Wall -Wextra -Iinclude -c src/avisos.c -o avisos.o
$ gcc -std=c17 -Wall -Wextra -Iinclude -c src/main.c -o main.o
$ gcc -o tamano main.o formato.o avisos.o
$ ./tamano tamano /etc/passwd /usr/lib/x86_64-linux-gnu/libc.so.6 noexiste; echo $?
  16.3 KiB  tamano
   1.3 KiB  /etc/passwd
   2.1 MiB  /usr/lib/x86_64-linux-gnu/libc.so.6
tamano: error: no se puede consultar 'noexiste'
1
$ ./tamano -v tamano noexiste
tamano: consultando tamano
  16.3 KiB  tamano
tamano: consultando noexiste
tamano: error: no se puede consultar 'noexiste'
$ gcc -std=c17 -Wall -Wextra -c src/main.c     # sin -I
src/main.c:6:10: fatal error: avisos.h: No such file or directory
    6 | #include "avisos.h"
      |          ^~~~~~~~~~

Recordemos del tema 3 que #include "…" busca primero en el directorio del archivo que incluye, que aquí es src, y después en la lista de directorios; los encabezados están en include, y sin -I no se encuentran. Para un proyecto pequeño también se puede compilar todo de una vez, gcc -Iinclude -o tamano src/*.c, pero entonces se recompila todo cada vez. El camino del código fuente al ejecutable es este:

5. Qué va en un encabezado

Un encabezado se copia, entero, en cada archivo que lo incluye. De ahí sale la regla de qué puede ir en él: declaraciones sí, definiciones no. Una declaración puede repetirse en muchos archivos sin problema; una definición crea algo, una función o una variable, y si se repite en dos archivos, el programa termina con dos cosas del mismo nombre.

Las definiciones de tipos son la excepción aparente: una struct se define en el encabezado y se repite en cada archivo que lo incluye. No es un problema, porque un tipo no ocupa memoria ni genera símbolos para el enlazador; solo le dice al compilador la forma de los datos. Fíjate también en que formato.h incluye stddef.h: un encabezado debe poder incluirse solo, sin depender de que quien lo incluye haya incluido antes lo que él necesita.

La prueba de que una definición en un encabezado es un error es fácil de hacer. Este config.h define una variable, y dos archivos lo incluyen:

$ gcc -std=c17 -Wall -Wextra -o config uno.c dos.c
/usr/bin/x86_64-linux-gnu-ld.bfd: /tmp/cclOvpWM.o:(.data+0x0): multiple definition of `nivel'; /tmp/ccaW75HA.o:(.data+0x0): first defined here
collect2: error: ld returned 1 exit status

Cada archivo compiló bien por separado, y cada uno creó su propia variable nivel. El error apareció recién al enlazar, cuando el enlazador encontró dos definiciones del mismo símbolo: el multiple definition que vimos en el tema 4.

6. Cada .c incluye su propio encabezado

formato.c incluye formato.h, aunque no lo necesita para compilar: sus funciones ya están definidas en él mismo. Lo incluye para que el compilador compare la declaración pública con la definición. Sin esa inclusión, nada garantiza que coincidan, y el resultado puede ser desastroso. En este caso, el encabezado dice que doble recibe y devuelve int, pero la implementación, en otro archivo que no incluye el encabezado, usa double:

$ gcc -std=c17 -Wall -Wextra -o usa_doble usa_doble.c doble.c && ./usa_doble
doble(21) = -1992188440
$ gcc -std=c17 -Wall -Wextra -c doble_bien.c     # la misma definición, pero incluyendo doble.h
doble_bien.c:4:8: error: conflicting types for ‘doble’; have ‘double(double)’
    4 | double doble(double x)
      |        ^~~~~
In file included from doble_bien.c:2:
doble.h:1:5: note: previous declaration of ‘doble’ with type ‘int(int)’
    1 | int doble(int x);
      |     ^~~~~

La primera compilación no dio ninguna advertencia, y el programa mostró un número absurdo. Cada archivo era correcto en sí mismo: usa_doble.c pasó un int en el registro %edi, según el prototipo que conocía, y esperó el resultado en %eax; doble.c, compilado por separado, buscó su argumento double en %xmm0 y dejó el resultado en otro registro de punto flotante, por la convención del tema 12. El compilador nunca vio los dos archivos a la vez, y el enlazador solo compara nombres, no tipos. Con el encabezado incluido en la implementación, el mismo error se convierte en un conflicting types al compilar.

Es una regla que no tiene excepciones: cada .c incluye su propio .h, y conviene que sea su primer #include, lo que además comprueba que el encabezado se puede incluir solo. Como red de seguridad adicional, la optimización en tiempo de enlace, -flto, ve todo el programa a la vez y detecta estos desacuerdos: con el mismo par de archivos, advierte type of ‘doble’ does not match original declaration [-Wlto-type-mismatch].

7. Variables compartidas: extern

Una variable global se comparte entre archivos con la misma lógica que una función: una sola definición, en un .c, y una declaración en el encabezado. Para una variable, la declaración sin definición se escribe con extern:

Con este esquema, main.c escribe avisos_detalle = 1 y avisos.c lo lee, y los dos hablan de la misma variable, porque el enlazador resuelve el nombre en la única definición. Para las funciones, extern es implícito: un prototipo ya es una declaración, y escribir extern delante no cambia nada.

Las definiciones tentativas tienen una historia que todavía se ve. Hasta gcc 10, dos archivos con int contador; sin valor, sin extern, se fusionaban silenciosamente en una sola variable, un comportamiento llamado common. Desde gcc 10, el comportamiento por omisión es el del estándar, y es un error:

$ gcc -std=c17 -Wall -Wextra -o cc c1.c c2.c
/usr/bin/x86_64-linux-gnu-ld.bfd: /tmp/ccEhu3cM.o:(.bss+0x0): multiple definition of `contador'; /tmp/ccZS8uOx.o:(.bss+0x0): first defined here
collect2: error: ld returned 1 exit status
$ gcc -std=c17 -Wall -Wextra -fcommon -o cc c1.c c2.c; echo $?
0

Muchos programas antiguos dejaron de compilar con el cambio, y la opción -fcommon recupera el comportamiento viejo. Es mejor no necesitarla: una definición, en un solo .c, y extern en el encabezado.

Que se pueda compartir una variable no significa que convenga, como discutimos en el tema 6. avisos_detalle es un caso razonable, estado de todo el programa que se fija una vez; aun así, muchos módulos prefieren no exponer la variable y ofrecer una función, como avisos_detallar(1), que deja al módulo el control de su estado.

8. Lo privado: static

En avisos.c, la variable programa y la función emitir son static: tienen enlace interno, y no existen para los demás archivos. Son detalles de la implementación, y declararlas static lo garantiza. La ventaja se ve cuando dos archivos usan el mismo nombre para cosas distintas:

$ gcc -std=c17 -Wall -Wextra -o ayud a.c b.c
/usr/bin/x86_64-linux-gnu-ld.bfd: /tmp/cci0iYil.o: in function `ayudante':
b.c:(.text+0x0): multiple definition of `ayudante'; /tmp/cc7kRgJt.o:a.c:(.text+0x0): first defined here
collect2: error: ld returned 1 exit status
$ sed -i 's/^int ayudante/static int ayudante/' a.c b.c
$ gcc -std=c17 -Wall -Wextra -o ayud a.c b.c && ./ayud
1 2

Sin static, los dos ayudante chocan. Con static, cada archivo tiene la suya, invisible para el otro, y el programa funciona: desde_a(), en a.c, llama a la de a.c, que devuelve 1, y main, en b.c, a la de b.c, que devuelve 2. En un proyecto con muchos archivos, y con bibliotecas de terceros, los choques de nombres son una amenaza real. La regla del tema 6 se vuelve imprescindible: todo lo que no está en el .h es static.

9. Las guardas de inclusión

Un encabezado puede incluir a otros, y un archivo puede terminar incluyendo el mismo encabezado dos veces sin darse cuenta: directamente y a través de otro. Con un encabezado que solo tiene prototipos no pasa nada, porque las declaraciones se pueden repetir; pero las definiciones de tipos no:

$ gcc -std=c17 -Wall -Wextra -c dibujo.c
In file included from figura.h:1,
                 from dibujo.c:2:
punto.h:1:8: error: redefinition of ‘struct punto’
    1 | struct punto {
      |        ^~~~~
In file included from dibujo.c:1:
punto.h:1:8: note: originally defined here
    1 | struct punto {
      |        ^~~~~

La solución es una guarda de inclusión, las tres líneas que rodean formato.h y avisos.h:

#ifndef FORMATO_H          /* si todavía no se definió FORMATO_H... */
#define FORMATO_H          /* ...se define ahora */

/* todo el contenido del encabezado */

#endif                     /* fin del bloque condicional */

La primera vez que el preprocesador procesa el archivo, FORMATO_H no existe, de modo que entra al bloque y lo define. La segunda vez, ya existe, y el preprocesador salta todo hasta el #endif: el contenido aparece una sola vez. Es la compilación condicional que se estudia en el tema 14. El nombre de la macro tiene que ser único en todo el proyecto, y la convención es derivarlo del nombre del archivo. La biblioteca de C hace exactamente lo mismo:

$ grep -n '_STDIO_H' /usr/include/stdio.h | head -n 2
24:#ifndef _STDIO_H
25:#define _STDIO_H	1

La biblioteca usa nombres que empiezan con guion bajo y mayúscula, reservados para la implementación como vimos en el tema 3; los encabezados propios no deben imitarla en eso. La alternativa #pragma once, una sola línea al principio del archivo, hace lo mismo y la entienden gcc, clang y casi todos los compiladores, pero no es parte del estándar de C. Las dos formas son aceptables; lo que no es aceptable es un encabezado sin ninguna de las dos.

10. El programa visto por el enlazador

nm muestra cómo quedó repartido el programa entre los objetos. Las letras son las del tema 6: mayúscula para lo visible desde otros archivos, minúscula para lo static, U para lo que se usa pero está definido en otra parte:

$ nm formato.o
0000000000000000 T formato_tamano
                 U snprintf
0000000000000000 d unidades
$ nm avisos.o
                 U __stack_chk_fail
0000000000000000 B avisos_detalle
0000000000000089 T avisos_error
000000000000015f T avisos_info
000000000000006f T avisos_iniciar
0000000000000000 t emitir
                 U fprintf
                 U fputc
0000000000000000 d programa
                 U stderr
                 U vfprintf
$ nm main.o
                 U __stack_chk_fail
                 U avisos_detalle
                 U avisos_error
                 U avisos_info
                 U avisos_iniciar
                 U formato_tamano
0000000000000000 T main
                 U printf
                 U stat
                 U strcmp

La salida es la interfaz del proyecto, vista desde abajo. Cada símbolo que main.o necesita (U) lo define en mayúscula otro objeto: formato_tamano está en formato.o, y avisos_detalle, la variable compartida, en avisos.o, en .bss porque vale 0. Lo privado, unidades, programa y emitir, aparece en minúscula: el enlazador lo ve, pero no deja que otro objeto lo use. Y los U que no define ningún objeto propio, como printf o stat, los resolverá la biblioteca de C. Este es el trabajo del enlazador que el tema 31 estudia a fondo.

11. Las dependencias entre archivos

Un objeto depende de su .c y de todos los encabezados que este incluye. El compilador puede calcular esa lista con -MM:

$ gcc -Iinclude -MM src/*.c
avisos.o: src/avisos.c include/avisos.h
formato.o: src/formato.c include/formato.h
main.o: src/main.c include/avisos.h include/formato.h

Si cambia formato.h, hay que recompilar formato.o y main.o, aunque no haya cambiado ningún .c. Olvidarlo no siempre produce un error: puede producir un programa que funciona mal. Este ejemplo tiene un módulo con una estructura en su encabezado, y un programa que la usa:

struct registro {
    int id;
    int valor;
};

void mostrar(struct registro r);

$ gcc -std=c17 -Wall -Wextra -c registro.c usa_registro.c
$ gcc -o registro registro.o usa_registro.o && ./registro
id = 7, valor = 42
$ sed -i 's/    int id;/    long marca;\n    int id;/' registro.h     # nuevo primer campo
$ gcc -std=c17 -Wall -Wextra -c registro.c                    # solo este
$ gcc -o registro registro.o usa_registro.o && ./registro
id = -628326488, valor = 32766

Ni una advertencia, y datos absurdos. registro.o se compiló con la estructura nueva, que tiene un long al principio, y usa_registro.o sigue con la vieja: los dos objetos tienen ideas distintas de dónde está cada campo, y se pasan la estructura sin saberlo. Es el mismo problema de la sección 6, ahora causado por una compilación incompleta. La única defensa es recompilar todo lo que depende del encabezado modificado, y como hacerlo a mano no escala, es exactamente lo que automatiza make con la información de -MM, en los temas 35 y 36. Ante una duda, recompilar todo.

Al recompilar los dos archivos, apareció además una advertencia que antes no estaba: missing initializer for field ‘valor’. El programa inicializaba la estructura con {7, 42}, y con el campo nuevo al principio, el 7 fue a marca y el 42 a id. Cambiar una estructura que se inicializa por posición tiene sus propios riesgos; el tema 24 muestra la forma de inicializar por nombre de campo, {.id = 7, .valor = 42}, que es inmune a este cambio.

12. Funciones en los encabezados

Hay un caso en que el código de una función sí va en un encabezado: funciones muy pequeñas, que conviene expandir en línea en cada lugar donde se usan, como las del tema 11. Se definen static inline:

#ifndef UNIDADES_H
#define UNIDADES_H

#include <stddef.h>

static inline size_t kib_a_bytes(size_t kib)
{
    return kib * 1024;
}

#endif

El static es lo que lo hace correcto: cada archivo que incluye el encabezado obtiene su propia copia privada, de modo que no hay multiple definition, y el compilador la expande en línea y no deja ninguna copia si no hace falta. El núcleo Linux usa este patrón en miles de funciones. Para funciones de más de unas pocas líneas, lo correcto sigue siendo un prototipo en el .h y el código en el .c.

13. Organizar y nombrar

Algunas convenciones hacen que un proyecto con muchos archivos se mantenga legible:

La última idea se puede llevar más lejos con los tipos opacos: un encabezado que declara struct conexion; sin definir sus campos, y funciones que reciben un puntero a ella. Quien usa el módulo no puede ver ni tocar el interior, solo usar las funciones. Es lo que hace la biblioteca de C con FILE, y lo veremos cuando lleguemos a las estructuras y los punteros.

14. Errores frecuentes

15. Resumen

• Un módulo es un par de archivos: el .h, con la interfaz, y el .c, con la implementación.
• Cada .c se compila por separado con -c y los objetos se enlazan al final; -I indica dónde buscar los encabezados.
• En un encabezado van declaraciones: prototipos, extern, tipos, constantes y funciones static inline. Las definiciones van en un solo .c.
• Cada .c incluye su propio .h, para que el compilador compruebe que la interfaz y la implementación coinciden; sin eso, un desacuerdo produce resultados absurdos sin advertencias.
• Una variable compartida se declara extern en el .h y se define, una vez, en un .c. Desde gcc 10, dos definiciones tentativas son un error.
• Todo lo que no está en el .h se declara static, para evitar choques de nombres.
• Las guardas de inclusión, o #pragma once, hacen que un encabezado incluido dos veces se procese una sola.
• nm muestra la interfaz desde el enlazador: T y D públicos, t y d privados, U pendientes.
• Un objeto depende de su .c y de sus encabezados (gcc -MM); cambiar un .h exige recompilar todo lo que lo incluye.
• Convenciones: prefijos por módulo, include/ y src/, encabezados autosuficientes e interfaces mínimas.

16. Preguntas de repaso

Intenta responder cada una antes de abrir la respuesta.

Para practicar

1. Reproduce el proyecto tamano con la misma estructura de directorios, compílalo por partes y comprueba con nm qué símbolos define y usa cada objeto.
2. Agrega al módulo avisos una función pública avisos_cantidad_errores(void) que devuelva cuántos errores se informaron, usando un contador static. Úsala en main para el código de salida, y elimina la variable errores de main.
3. Convierte avisos_detalle en una variable static de avisos.c y expón en su lugar void avisos_detallar(int activo). ¿Qué cambia en nm avisos.o?
4. Agrega un módulo permisos, con permisos.h y permisos.c, que contenga la función texto_permisos del tema 8, y haz que tamano muestre también los permisos de cada archivo.
5. Quita la guarda de formato.h e inclúyelo dos veces en main.c. ¿Hay error? ¿Por qué no, si en dibujo.c sí lo había? Agrega una struct al encabezado y vuelve a probar.
6. Cambia en formato.c el tipo del primer parámetro de formato_tamano a long, sin tocar el encabezado. Compila y explica el mensaje. Luego quita el #include "formato.h" de formato.c, compila todo y ejecuta: ¿qué pasa ahora?
7. Usa gcc -Iinclude -MM src/*.c y escribe a mano, a partir de su salida, la lista de órdenes que habría que ejecutar si cambiara solo avisos.h.