头文件

头文件：作用、内容、格式、路径、重复包含、实战多文件工程模板，写完直接 make 运行！

---

一、头文件的作用：公共接口仓库

通常，一个常规的C语言程序会包含多个源码文件（.c），当某些公共资源需要在各个源码文件中使用时，为了避免多次编写相同的代码，一般的做法是将这些大家都需要用到的公共资源放入头文件（.h）（声明，不建议在头文件中直接定义变量）当中，然后在各个源码文件中直接包含即可。

存放内容	是否可放 .h	可见范围	示例
全局变量 声明	✅	跨文件	extern int g_cnt;
普通函数 声明	✅	跨文件	void led_on(void);
静态函数 定义	✅	当前文件	static void helper() {}
宏定义	✅	跨文件	#define MAX(a,b) ((a)>(b)?(a):(b))
结构体/联合体/枚举 声明	✅	跨文件	struct node;
其他头文件	✅	递归展开	#include <stdint.h>
全局变量 定义	❌（例外见正文）	-	int g_cnt = 0;

> 口诀：声明放 .h，定义放 .c，避免多重定义符号

---

二、头文件内容模板（含卫士）

头文件中所存放的内容，就是各个源码文件的彼此可见的公共资源，包括：
1.全局变量的声明。
2.普通函数的声明。
3.静态函数的定义。
4.宏定义。
5.结构体、联合体的声明。
6.枚举常量列表的声明。
7.其他头文件。

// head.h
// extern  表示外部定义的内容
extern int global; // 1，全局变量的声明   （告诉编译器他存在与其他文件中）
extern void f1();  // 2，普通函数的声明


static void f2()   // 3，静态函数的定义
{
    ...
}

#define MAX(a, b) ((a)>(b)?(a):(b)) // 4，宏定义

struct node    // 5，结构体的声明
{
    ...
};
union attr    // 6，联合体的声明
{
    ...
};

#include <unistd.h> // 7，其他头文件
#include <string.h>
#include <stdint.h>

• 特别说明：
  a.全局变量、普通函数的定义一般出现在某个源文件（*.c *.cpp）中，其他的源文件想要使用都需要进行声明，因此一般放在头文件中更方便。
  a.静态函数、宏定义、结构体、联合体的定义都只能在其所在的文件可见，因此如果多个源文件都需要使用的话，放到头文件中定义是最方便，也是最安全的选择。

---

二、头文件的格式

由于头文件包含指令 #include 的本质是复制粘贴，并且一个头文件中可以嵌套包含其他头文件，因此很容易出现一种情况是：头文件被重复包含。

• 使用条件编译，解决头文件重复包含的问题，格式如下：

#ifndef _HEADNAME_H    //一般取头文件名称的大写
#define _HEADNAME_H

...
... (头文件正文)
...

#endif

---

三、头文件的使用

头文件编写好了之后，就可以被各个所需要的源码文件包含了，包含头文件的语句就是如下预处理指令：

// 使用尖括号 <> 来包含的头文件他默认从系统的路径中寻找
#include <stdio.h>

// 使用 “ ” 来包含的头文件除了从默认路径找以外还会优先在当前目录找
#include "main.h" 
#include "test.h"

可以看到，在源码文件中包含指定的头文件有两种不同的形式：

• 使用双引号：在指定位置 + 系统标准路径搜索 head.h
• 使用尖括号：在系统标准路径搜索 stdio.h

由于自定义的头文件一般放在源码文件的周围，因此需要在编译的时候通过特定的选项来指定位置，而系统头文件都统一放在标准路径下，一般无需指定位置。
假设在源码文件 main.c 中，包含了两个头文件：head.h 和 stdio.h ，由于他们一个是自定义头文件，一个是系统标准头文件，前者放在项目 pro/inc 路径下，后者存放于系统头文件标准路径下（一般位于 /usr/include），因此对于这个程序的编译指令应写作：

gec@ubuntu:~/pro$ gcc main.c -o main -I /home/gec/pro/inc

其中，/home/gec/pro/inc 是自定义头文件 head.h 所在的路径
语法要点：

• 预处理指令 #include 的本质是复制粘贴：将指定头文件的内容复制到源码文件中。
• 系统标准头文件路径可以通过编译选项 -v 来获知，比如：

gec@ubuntu:~/pro$ gcc main.c -I /home/gec/pro/inc -v
... ...
#include "..." search starts here:
#include <...> search starts here:
    /usr/lib/gcc/x86_64-linux-gnu/7/include
    /usr/local/include
    /usr/lib/gcc/x86_64-linux-gnu/7/include-fixed
    /usr/include/x86_64-linux-gnu
    /usr/include
... ...

---

四、多文件工程实战（LED 例程）

① 目录结构

led_project/
├── inc/
│   ├── led.h
│   └── board.h
├── src/
│   ├── main.c
│   └── led.c
├── Makefile

② 源文件 & 头文件
inc/led.h

#pragma once
#include <stdint.h>

void led_init(uint8_t pin);
void led_on(void);
void led_off(void);

src/led.c

#include "led.h"
static uint8_t g_pin;   // 文件内私有

void led_init(uint8_t pin) { g_pin = pin; }
void led_on(void)  { /* 写寄存器 */ }
void led_off(void) { /* 写寄存器 */ }

src/main.c

#include "led.h"
#include "board.h"

int main(void)
{
    board_init();
    led_init(5);
    while (1) {
        led_on();
        board_delay_ms(500);
        led_off();
        board_delay_ms(500);
    }
}

③ Makefile（一键编译）

CC      := gcc
CFLAGS  := -Wall -Wextra -I inc
SRC     := src/main.c src/led.c src/board.c
TARGET  := led_demo

$(TARGET): $(SRC)
	$(CC) $(CFLAGS) $^ -o $@

clean:
	rm -f $(TARGET) *.o

.PHONY: clean

使用：

make         # 编译
make clean   # 清理