LibOpenCM3(二) 項目模板 Makefile分析

• 2022 年 2 月 21 日
• 筆記
• linux, STM32, makefile, Mobile/Embed, LibOpenCM3

目錄

• LibOpenCM3(一) Linux下命令行開發環境配置
• LibOpenCM3(二) 項目模板 Makefile分析

LibOpenCM3 項目模板

項目模板地址: //github.com/libopencm3/libopencm3-template

如果僅僅用IDE開發, 並不需要了解 Makefile 結構. 對於需要實現自動化發布和測試的項目, Makefile 幾乎是默認的選項, 了解 Makefile 工作機制對項目長期的開發和維護都是很有幫助的.

文件結構

├── libopencm3                # libopencm3 封裝庫
│     ├── COPYING.GPL3
│     ├── COPYING.LGPL3
│     ├── doc
│     ├── HACKING
│     ├── HACKING_COMMON_DOC
│     ├── include
│     ├── ld
│     ├── lib                 # 編譯後, 鏈接庫 .a 文件的存放目錄
│     ├── locm3.sublime-project
│     ├── Makefile            # libopencm3 項目 Makefile
│     ├── mk
│     │     ├── gcc-config.mk
│     │     ├── gcc-rules.mk
│     │     ├── genlink-config.mk # 用於生成ld文件
│     │     ├── genlink-rules.mk  # 用於生成ld文件
│     │     └── README
│     ├── README.md
│     ├── scripts
│     └── tests
├── LICENSE
├── my-common-code           # 用於演示的公用程式碼部分
│     ├── api-asm.h
│     ├── api-asm.S
│     ├── api.c
│     └── api.h
├── my-project               # 用於演示的用戶項目程式碼部分
│     ├── Makefile           # 用戶項目 Makefile
│     └── my-project.c
├── README.md
└── rules.mk                 # 全局規則

其中, libopencm3 的 Makefile 用於將 libopencm3 編譯生成鏈接庫, 用戶項目的 Makefile 用於引用 libopencm3 以及包含公用程式碼生成最終的 elf 和 bin, 以及生成 ld 文件.

libopencm3 的 Makefile

libopencm3 的 Makefile 主要用於將 libopencm3 編譯為鏈接庫庫

# 注: 如果工具鏈未加入PATH, 可以在這裡加上路徑
PREFIX		?= arm-none-eabi-

# 注: 這個perl腳本貌似是用來檢查程式碼注釋的格式的
STYLECHECK      := scripts/checkpatch.pl
STYLECHECKFLAGS := --no-tree -f --terse --mailback

# 注: 這裡設置的編譯的範圍, 默認是編譯全部型號, 這會消耗很長的時間, 如果只需要編譯某一個型號, 可以在make時直接指定
#     例如 TARGETS=stm32/f1 make
#     這裡的名稱要和 lib 下的目錄名嚴格一致, 因為下面會用這個拼接完整目錄
# 
TARGETS ?=	stm32/f0 stm32/f1 stm32/f2 stm32/f3 stm32/f4 stm32/f7 \
		stm32/l0 stm32/l1 stm32/l4 \
		stm32/g0 \
		stm32/h7 \
		gd32/f1x0 \
		lpc13xx lpc17xx lpc43xx/m4 lpc43xx/m0 \
		lm3s lm4f msp432/e4 \
		efm32/tg efm32/g efm32/lg efm32/gg efm32/hg efm32/wg \
		efm32/ezr32wg \
		sam/3a sam/3n sam/3s sam/3u sam/3x sam/4l \
		sam/d \
		vf6xx \
		swm050 \
		pac55xx

# Be silent per default, but 'make V=1' will show all compiler calls.
# 注: 使用V=1輸出編譯時的完整命令, 例如 TARGETS=stm32/f1 make V=1
ifneq ($(V),1)
Q := @
# Do not print "Entering directory ...".
MAKEFLAGS += --no-print-directory
endif

# Avoid the use of shell find, for windows compatibility
IRQ_DEFN_FILES  := $(foreach TARGET,$(TARGETS),$(wildcard include/libopencm3/$(TARGET)/irq.json))
STYLECHECKFILES := $(wildcard include/*/*.h include/*/*/*.h include/*/*/*/*.h)
STYLECHECKFILES += $(wildcard lib/*/*.h lib/*/*/*.h lib/*/*/*/*.h)
STYLECHECKFILES += $(wildcard lib/*/*.c lib/*/*/*.c lib/*/*/*/*.c)

# 注: 默認的目標是 all -> build -> lib
all: build

build: lib

%.genhdr:
	@printf "  GENHDR  $*\n";
	# 注: irq2nvic_h 是個 python 腳本, 用JSON定義的中斷編號生成 nvic.h 頭文件
	$(Q)./scripts/irq2nvic_h ./$*;

%.cleanhdr:
	@printf "  CLNHDR  $*\n";
	$(Q)./scripts/irq2nvic_h --remove ./$*

# 注: 根據 TARGETS 拼接目錄
LIB_DIRS:=$(wildcard $(addprefix lib/,$(TARGETS)))
# 注: $(IRQ_DEFN_FILES:=.genhdr) 這個表達式, 實際上是批量替換, 替換的左邊擴展名為空, 
#     所以其作用是將 IRQ_DEFN_FILES 中每一個值, 加上了.genhdr, 去執行 %.genhdr 的規則
$(LIB_DIRS): $(IRQ_DEFN_FILES:=.genhdr)
	$(Q)$(RM) .stamp_failure_$(subst /,_,$@)
	@printf "  BUILD   $@\n";
	$(Q)$(MAKE) --directory=$@ PREFIX="$(PREFIX)" || \
		echo "Failure building: $@: code: $$?" > .stamp_failure_$(subst /,_,$@)

lib: $(LIB_DIRS)
	$(Q)$(RM) .stamp_failure_tld
	$(Q)for failure in .stamp_failure_*; do \
		[ -f $$failure ] && cat $$failure >> .stamp_failure_tld || true; \
	done;
	$(Q)[ -f .stamp_failure_tld ] && cat .stamp_failure_tld && exit 1 || true;

# 注: 執行 doc 目錄下的 make
html doc:
	$(Q)$(MAKE) -C doc html TARGETS="$(TARGETS)"

# 注: 清理, 這些$(XXX:=.xxx)也是批量替換用法
clean: $(IRQ_DEFN_FILES:=.cleanhdr) $(LIB_DIRS:=.clean) $(EXAMPLE_DIRS:=.clean) doc.clean styleclean genlinktests.clean

%.clean:
	$(Q)if [ -d $* ]; then \
		printf "  CLEAN   $*\n"; \
		$(MAKE) -C $* clean || exit $?; \
	fi;
	$(Q)$(RM) .stamp_failure_*;


stylecheck: $(STYLECHECKFILES:=.stylecheck)
styleclean: $(STYLECHECKFILES:=.styleclean)

# the cat is due to multithreaded nature - we like to have consistent chunks of text on the output
%.stylecheck: %
	$(Q)if ! grep -q "* It was generated by the irq2nvic_h script." $* ; then \
		$(STYLECHECK) $(STYLECHECKFLAGS) $* > $*.stylecheck; \
		if [ -s $*.stylecheck ]; then \
			cat $*.stylecheck; \
		else \
			rm -f $*.stylecheck; \
		fi; \
	fi;

%.styleclean:
	$(Q)rm -f $*.stylecheck;


LDTESTS		:=$(wildcard ld/tests/*.data)

genlinktests: $(LDTESTS:.data=.ldtest)
genlinktests.clean:
	$(Q)rm -f $(LDTESTS:.data=.out)

%.ldtest:
	@if ./scripts/genlinktest.sh $* >/dev/null; then\
		printf "  TEST  OK  : $*\n";		\
	else						\
		printf "  TEST FAIL : $*\n";		\
	fi;


.PHONY: build lib $(LIB_DIRS) doc clean generatedheaders cleanheaders stylecheck genlinktests genlinktests.clean

rule.mk 分析

多匹配的優先順序選擇, 參考 How Patterns Match 模式匹配的工作機制

# This version of rules.mk expects the following to be defined before
# inclusion..
### REQUIRED ###
# OPENCM3_DIR - duh
# PROJECT - will be the basename of the output elf, eg usb-gadget0-stm32f4disco
# CFILES - basenames only, eg main.c blah.c
# CXXFILES - same for C++ files. Must have cxx suffix!
# DEVICE - the full device name, eg stm32f405ret6
#  _or_
# LDSCRIPT - full path, eg ../../examples/stm32/f4/stm32f4-discovery/stm32f4-discovery.ld
# OPENCM3_LIB - the basename, eg: opencm3_stm32f4
# OPENCM3_DEFS - the target define eg: -DSTM32F4
# ARCH_FLAGS - eg, -mthumb -mcpu=cortex-m4 -mfloat-abi=hard -mfpu=fpv4-sp-d16
#    (ie, the full set of cpu arch flags, _none_ are defined in this file)
#
### OPTIONAL ###
# INCLUDES - fully formed -I paths, if you want extra, eg -I../shared
# BUILD_DIR - defaults to bin, should set this if you are building multiarch
# OPT - full -O flag, defaults to -Os
# CSTD - defaults -std=c99
# CXXSTD - no default.
# OOCD_INTERFACE - eg stlink-v2
# OOCD_TARGET - eg stm32f4x
#    both only used if you use the "make flash" target.
# OOCD_FILE - eg my.openocd.cfg
#    This overrides interface/target above, and is used as just -f FILE
### TODO/FIXME/notes ###
# No support for stylecheck.
# No support for BMP/texane/random flash methods, no plans either
# No support for magically finding the library.
# C++ hasn't been actually tested with this..... sorry bout that. ;)
# Second expansion/secondary not set, add this if you need them.

# 注: 指定默認的中間文件目錄
BUILD_DIR ?= bin
OPT ?= -Os
CSTD ?= -std=c99

# Be silent per default, but 'make V=1' will show all compiler calls.
# If you're insane, V=99 will print out all sorts of things.
V?=0
ifeq ($(V),0)
Q	:= @
NULL	:= 2>/dev/null
endif

# Tool paths.
PREFIX	?= arm-none-eabi-
CC	= $(PREFIX)gcc
CXX	= $(PREFIX)g++
LD	= $(PREFIX)gcc
OBJCOPY	= $(PREFIX)objcopy
OBJDUMP	= $(PREFIX)objdump
OOCD	?= openocd

OPENCM3_INC = $(OPENCM3_DIR)/include

# Inclusion of library header files
INCLUDES += $(patsubst %,-I%, . $(OPENCM3_INC) )

# 注: 格式 $(SRC:%.c=%.o) 批量替換, 在SRC中找到所有.c 結尾的文件，然後把所有的.c換成.o
# 等價於 $(patsubst %.c, %.o, $(SRC))
OBJS = $(CFILES:%.c=$(BUILD_DIR)/%.o)
OBJS += $(CXXFILES:%.cxx=$(BUILD_DIR)/%.o)
OBJS += $(AFILES:%.S=$(BUILD_DIR)/%.o)
GENERATED_BINS = $(PROJECT).elf $(PROJECT).bin $(PROJECT).map $(PROJECT).list $(PROJECT).lss

TGT_CPPFLAGS += -MD
TGT_CPPFLAGS += -Wall -Wundef $(INCLUDES)
TGT_CPPFLAGS += $(INCLUDES) $(OPENCM3_DEFS)

TGT_CFLAGS += $(OPT) $(CSTD) -ggdb3
TGT_CFLAGS += $(ARCH_FLAGS)
TGT_CFLAGS += -fno-common
TGT_CFLAGS += -ffunction-sections -fdata-sections
TGT_CFLAGS += -Wextra -Wshadow -Wno-unused-variable -Wimplicit-function-declaration
TGT_CFLAGS += -Wredundant-decls -Wstrict-prototypes -Wmissing-prototypes

TGT_CXXFLAGS += $(OPT) $(CXXSTD) -ggdb3
TGT_CXXFLAGS += $(ARCH_FLAGS)
TGT_CXXFLAGS += -fno-common
TGT_CXXFLAGS += -ffunction-sections -fdata-sections
TGT_CXXFLAGS += -Wextra -Wshadow -Wredundant-decls  -Weffc++

TGT_ASFLAGS += $(OPT) $(ARCH_FLAGS) -ggdb3

TGT_LDFLAGS += -T$(LDSCRIPT) -L$(OPENCM3_DIR)/lib -nostartfiles
TGT_LDFLAGS += $(ARCH_FLAGS)
TGT_LDFLAGS += -specs=nano.specs
TGT_LDFLAGS += -Wl,--gc-sections
# OPTIONAL
#TGT_LDFLAGS += -Wl,-Map=$(PROJECT).map
ifeq ($(V),99)
TGT_LDFLAGS += -Wl,--print-gc-sections
endif

# Linker script generator fills this in for us.
# 注: 判斷變數是否為空的格式 ifeq ($(TEST),) TEST := $(something else) endif
ifeq (,$(DEVICE))
LDLIBS += -l$(OPENCM3_LIB)
endif
# nosys is only in newer gcc-arm-embedded...
#LDLIBS += -specs=nosys.specs
LDLIBS += -Wl,--start-group -lc -lgcc -lnosys -Wl,--end-group

# Burn in legacy hell fortran modula pascal yacc idontevenwat
.SUFFIXES:
.SUFFIXES: .c .S .h .o .cxx .elf .bin .list .lss

# Bad make, never *ever* try to get a file out of source control by yourself.
%: %,v
%: RCS/%,v
%: RCS/%
%: s.%
%: SCCS/s.%

# 注: 默認目標, 需要產生項目elf和bin文件
all: $(PROJECT).elf $(PROJECT).bin
# 注: flash目標, 需要 項目.flash, 會定向到 %.flash 任務
flash: $(PROJECT).flash

# error if not using linker script generator
ifeq (,$(DEVICE))
$(LDSCRIPT):
ifeq (,$(wildcard $(LDSCRIPT)))
    $(error Unable to find specified linker script: $(LDSCRIPT))
endif
else
# if linker script generator was used, make sure it's cleaned.
# 將 ld 文件加入二進位文件列表, 用於 clean 的時候清除
GENERATED_BINS += $(LDSCRIPT)
endif

# Need a special rule to have a bin dir
# 注: 匹配 BUILD_DIR 目錄下的 .o 文件目標, 檢查 .c 文件, 並對應的調用 CC 進行編譯
# 匹配規則和優先順序順序參考 GNU Make 手冊的 10.5.4 How Patterns Match
$(BUILD_DIR)/%.o: %.c
	@printf "  CC\t$<\n"
	@mkdir -p $(dir $@)
	$(Q)$(CC) $(TGT_CFLAGS) $(CFLAGS) $(TGT_CPPFLAGS) $(CPPFLAGS) -o $@ -c $<

$(BUILD_DIR)/%.o: %.cxx
	@printf "  CXX\t$<\n"
	@mkdir -p $(dir $@)
	$(Q)$(CXX) $(TGT_CXXFLAGS) $(CXXFLAGS) $(TGT_CPPFLAGS) $(CPPFLAGS) -o $@ -c $<

$(BUILD_DIR)/%.o: %.S
	@printf "  AS\t$<\n"
	@mkdir -p $(dir $@)
	$(Q)$(CC) $(TGT_ASFLAGS) $(ASFLAGS) $(TGT_CPPFLAGS) $(CPPFLAGS) -o $@ -c $<

# 注: LIBDEPS 定義在 genlink-config.mk, 指向 libopencm3/lib/libopencm3_xxxx.a 文件,
# 根據設置的 DEVICE 不同, 名稱不同
$(PROJECT).elf: $(OBJS) $(LDSCRIPT) $(LIBDEPS)
	@printf "  LD\t$@\n"
	$(Q)$(LD) $(TGT_LDFLAGS) $(LDFLAGS) $(OBJS) $(LDLIBS) -o $@

# 注: 用 .elf 文件生成 .bin 文件
%.bin: %.elf
	@printf "  OBJCOPY\t$@\n"
	$(Q)$(OBJCOPY) -O binary  $< $@

%.lss: %.elf
	$(OBJDUMP) -h -S $< > $@

%.list: %.elf
	$(OBJDUMP) -S $< > $@

# 注: 燒錄
%.flash: %.elf
	@printf "  FLASH\t$<\n"
ifeq (,$(OOCD_FILE))
	$(Q)(echo "halt; program $(realpath $(*).elf) verify reset" | nc -4 localhost 4444 2>/dev/null) || \
		$(OOCD) -f interface/$(OOCD_INTERFACE).cfg \
		-f target/$(OOCD_TARGET).cfg \
		-c "program $(realpath $(*).elf) verify reset exit" \
		$(NULL)
else
	$(Q)(echo "halt; program $(realpath $(*).elf) verify reset" | nc -4 localhost 4444 2>/dev/null) || \
		$(OOCD) -f $(OOCD_FILE) \
		-c "program $(realpath $(*).elf) verify reset exit" \
		$(NULL)
endif

clean:
	rm -rf $(BUILD_DIR) $(GENERATED_BINS)

.PHONY: all clean flash
-include $(OBJS:.o=.d)

my-project 的 Makefile

用戶項目的 Makefile 主要用於定義一些路徑和名稱變數, 最後是引用 genlink-config.mk, rules.mk, genlink-rules.mk 這三個文件進行編譯

# 注: 設置項目輸出的韌體文件名
PROJECT = awesomesauce
# 注: 編譯中間產物的存放目錄
BUILD_DIR = bin

# 注: 下面會將這個目錄設置為 VPATH, 用於放置共用程式碼或其它的庫
SHARED_DIR = ../my-common-code
# 注: 編譯項目時需要添加的C文件
CFILES = my-project.c
CFILES += api.c
# 注: 彙編文件
AFILES += api-asm.S

# TODO - you will need to edit these two lines!
# 注: MCU型號, 用於生成ld文件
DEVICE=stm32f103c6t6
# 注: 用於 openocd 下載和調試的配置文件, 如果不用 openocd, 可以不管
OOCD_FILE = board/stm32f4discovery.cfg
# 注: 如果不設置PATH, 這裡要把工具鏈的路徑加上
PREFIX	?= /opt/gcc-arm/gcc-arm-none-eabi-10.3-2021.10/bin/arm-none-eabi-

# You shouldn't have to edit anything below here.
VPATH += $(SHARED_DIR)
# 注: 頭文件路徑, libopencm3在rules.mk中會包含, 這裡不需要寫
INCLUDES += $(patsubst %,-I%, . $(SHARED_DIR))
OPENCM3_DIR=../libopencm3

include $(OPENCM3_DIR)/mk/genlink-config.mk
include ../rules.mk
include $(OPENCM3_DIR)/mk/genlink-rules.mk