GNU大型项目构建和覆盖率生成（第一篇）

目录

• 0. 序言
• 1. 项目描述
• 2. 项目构建
  • 2.1 编译规则
  • 2.2 构建过程
• 3. 覆盖率分析

---

0. 序言

在开始正文之前，请允许我先说明一下本文的目的和写作的动机，好让读者不惑。

我们知道，在Linux环境中，很多软件的组织都遵循GNU软件标准。不论是自己开发GNU软件还是阅读别人写好的源程序，能了解、熟悉GNU项目的构建方式，对我们的工作会起到事半功倍的效果。本文的目的，就是从零开始，告诉大家怎么构建一个GNU项目，如何阅读GNU源程序。

文章会涉及到的工具有：

• automake
• autoconf
• aclocal
• gcc、gfotran
• makefile
• libtool
• gcov、 gcovr

在阅读本文之前，上述工具需要安装部署完成，同时期望读者对一下的知识和技能有一定的了解和掌握：

1. C、C++、Fortran语言
2. 基本的编译、链接过程和原理
3. Makefile基本知识
4. Linux-shell基本命令

不要被前面的要求吓到，笔者也是从对上面知识一无所知，经过两三周时间摸索，写出了这篇文章的。文章内容涉及到的知识不够深刻，但是基本上可以帮助像半个月前的笔者一样茫然的入门者。文章中不严谨的表述或者表述、理解方面的错误，欢迎大家留言指正。

另外，本文只是告诉大家如何快速的完成一个GNU项目。其中涉及到的autotools工具和相关语言的细节，请大家阅读文章后面的链接文章。

好了，我们开始正文！

---

1. 项目描述

这一章节，主要说明我们的目的：

我们最终要完成一个deep风格的项目组织。项目使用c和Fortran混合编程，利用GNU-autotools来完成项目构建，利用gcov完成项目覆盖率分析。最后形成通过覆盖率分析优化后的项目发布包。该发布包能够直接发布在网络，供其他用户下载、安装并使用。

项目最终的目录如下：

➜  csdemo tree
.
├── AUTHORS
├── auto.sh
├── ChangeLog
├── data
│   └── thch
│       └── JANAF
├── doc
│   └── README
├── examples
├── makeconfig
│   └── make.global
├── NEWS
├── preprocessor
├── README
├── src
│   ├── alge
│   │   ├── alge.c
│   │   └── alge.h
│   ├── apps
│   │   └──csrun.c
│   ├── base
│   │   ├── addfld.f90
│   │   └── paramx.f90
│   ├── bft
│   │   ├── bft.c
│   │   └──bft.h
│   ├── cdo
│   │   ├── cdo.c
│   │   └──cdo.h
│   ├── cogz
│   │   └── matmul.f90
│   ├── comb
│   │   ├── comb.c
│   │   └──comb.h
│   └── lib
└── test

读者可以在这里下载源码。

下面我们就通过几个章节的内容，详细的说明如何从零开始生成这个项目。

---

2. 项目构建

我们将这个项目放置在csdemo路径下面：

这里：data路径下面存放项目的数据文件，doc为项目的说明文档，examples存放用户案例，test存放测试用例，preprocessor存放前处理相关程序，src存放主体程序代码。在src下面alge是c语言文件，apps是用户可执行程序，其他子文件夹分别完成一些特定的功能。

将下载到的源码分别复制进对应的路径得到如上文的项目组织。下一步我们就要开始进行项目构建。

项目的构建一般可以通过一下几步来完成：

1. 在每个需要编译的子路径下面编写编译规则Makefile.am文件。
2. 在根目录（项目根目录）下执行autoscan命令，形成configure.scan文件
3. 将configure.scan文件命名为configure.ac
4. 按照规则修改configure.ac文件
5. 执行aclocal文件，形成m4宏命令（有时需要手动编写m4宏）
6. 执行autoheader命令生成头文件
7. 执行autoconf形成config文件
8. 执行libtoolize --automake声明automake宏（这一步按情况选择执行）
9. 执行automake -a命令，生成makefile.in文件
10. 执行./configure命令，生成makefile文件

至此，一个典型的GNU项目构建完成。至于每一步怎么操作，后文会详细给出。

在完成上面操作之后，我们就可以发布自己的软件，用户通过：

./configure

make

make install

轻松完成软件的安装和配置。后面的三个命令是不是很熟悉。

2.1 编译规则

坚持往下走。我们先来完成第一步，源码的编译。这一步您需要对gcc编译和链接有一定的了解，同时如果您知道目标文件、静态库、动态库就更好了，他能帮助我们更好的完成本节的内容。

我们平时对于单个或者少量的源文件直接用gcc编译链接，中等大小的项目我们可以手写Makefile，但是对于多文件，手写Makefile仍然很繁琐，这个时候我们就可以使用autotools套件中的automake来自动生成makefile文件。

1. 我们在根目录下建立文件Makefile.am，编写如下内容：

## ./Makefile.am   ## 双#表示注释
SUBDIRS          = src      ## 递归子文件夹
## 需要打包发布的文件夹和文件
EXTRA_DIST       = doc data examples preprocessor test

1. 进入到src下面，建立Makefile.am，编写如下内容：

##./src/Makefile.am
SUBDIRS          = alge base bft cdo comb cogz apps
EXTRA_DIST       = lib

1. 进入到src/alge下面，建立Makefile.am，编写如下内容：

##./src/alge/Makefile.am
noinst_LIBRARIES   = libalge.a   ## 生成静态库，前缀noinst表示不安装。
libalge_a_SOURCES = alge.c

AM_CPPFLAGS      = -I$(top_srcdir)/src/alge  ## AM_CPPFLAGS给出头文件路径

1. 进入到src/apps下面，建立Makefile.am，编写如下内容：

##./src/apps/Makefile.am
bin_PROGRAMS  = csrun
csrun_SOURCES = csrun.c

## 头文件
csrun_CPPFLAGS    =      \
-I$(top_srcdir)/src/alge \
-I$(top_srcdir)/src/bft  \
-I$(top_srcdir)/src/cdo  \
-I$(top_srcdir)/src/comb 

## 依赖静态库
csrun_LDADD      = \
$(top_srcdir)/src/alge/libalge.a \
$(top_srcdir)/src/bft/libbft.a   \
$(top_srcdir)/src/cdo/libcdo.a   \
$(top_srcdir)/src/comb/libcomb.a \
$(top_srcdir)/src/base/libbase.a \
$(top_srcdir)/src/cogz/libcogz.a 

AM_CFLAGS = -lgfortran

1. 进入到src/base下面，建立Makefile.am，编写如下内容：

##./src/base/Makefile.am
noinst_LIBRARIES = libbase.a
libbase_a_SOURCES = addfld.f90

AM_FCFLAGS      = -I$(top_srcdir)/src/base

1. 进入到src/bft下面，建立Makefile.am，编写如下内容：

##./src/bft/Makefile.am
noinst_LIBRARIES   = libbft.a
libbft_a_SOURCES = bft.c

AM_CPPFLAGS      = -I$(top_srcdir)/src/bft

1. 进入到src/cdo下面，建立Makefile.am，编写如下内容：

##./src/cdo/Makefile.am
noinst_LIBRARIES   = libcdo.a
libcdo_a_SOURCES = cdo.c

AM_CPPFLAGS      = -I$(top_srcdir)/src/cdo

1. 进入到src/cogz下面，建立Makefile.am，编写如下内容：

##./src/cogz/Makefile.am
noinst_LIBRARIES = libcogz.a
libcogz_a_SOURCES = matmul.f90

1. 进入到src/comb下面，建立Makefile.am，编写如下内容：

##./src/comb/Makefile.am
noinst_LIBRARIES   = libcomb.a
libcomb_a_SOURCES = comb.c

AM_CPPFLAGS      = -I$(top_srcdir)/src/comb

为了编写方便，本文案例中都是用生成静态库的方式来完成模块目录的编译。当然，用户也可以生成动态库或者目标文件（automake文档中没有明确的对目标文件的支持，但其实可以使用automake生成目标文件）。

至此，我们完成了项目构建十步中的第一步。（不用怕，后面的基本都是输入命令，不用编写大量文件。）

2.2 构建过程

1. 在完成第一步工作的基础上，在根目录执行：

autoscan

在根目录生成两个文件：configure.scan、autoscan.log。后者在我们执行这条命令出错时帮助我们查找问题，这里主要关注第一个文件。

1. 将configure.scan重命名为configure.ac
2. 打开configure.ac文件

#                                               -*- Autoconf -*-
# Process this file with autoconf to produce a configure script.

AC_PREREQ([2.69])
AC_INIT([FULL-PACKAGE-NAME], [VERSION], [BUG-REPORT-ADDRESS])
AC_CONFIG_SRCDIR([src/cdo/cdo.h])
AC_CONFIG_HEADERS([config.h])

# Checks for programs.
AC_PROG_CC
AC_PROG_MAKE_SET

# Checks for libraries.
# FIXME: Replace `main' with a function in `-lgfortran':
AC_CHECK_LIB([gfortran], [main])

# Checks for header files.

# Checks for typedefs, structures, and compiler characteristics.

# Checks for library functions.

AC_CONFIG_FILES([Makefile
                 src/Makefile
                 src/alge/Makefile
                 src/apps/Makefile
                 src/base/Makefile
                 src/bft/Makefile
                 src/cdo/Makefile
                 src/cogz/Makefile
                 src/comb/Makefile])
AC_OUTPUT

1. 修改文件成如下（修改的地方打上了注释，一个#开始为注释）：

#                                               -*- Autoconf -*-
# Process this file with autoconf to produce a configure script.

AC_PREREQ([2.69])
AC_INIT(csrun, 1.0, mx@mx.com)  # 三个参数分别为：项目名称、版本号、bug提交邮箱
AC_CONFIG_SRCDIR([src/apps/csrun.c])
AC_CONFIG_HEADERS([config.h])
AM_INIT_AUTOMAKE[foreign tar-pax]  # 这行必须添加，用来指明与automake联用
# Checks for programs.
AC_PROG_CC                       # 查询c编译器
AC_PROG_FC                       # 查询Fortran编译器

# Checks for libraries.

# Checks for header files.
AC_PROG_RANLIB                  # 启用静态库编译

# Checks for typedefs, structures, and compiler characteristics.

# Checks for library functions.

AC_CONFIG_FILES([Makefile
                 src/Makefile
				 src/apps/Makefile
				 src/alge/Makefile
                 src/base/Makefile
                 src/bft/Makefile
				 src/cdo/Makefile
                 src/comb/Makefile
				 src/cogz/Makefile])  # 这里需要指明生成Makefile的路径
AC_OUTPUT

1. 执行aclocal命令，这个命令会生成一些m4文件。暗示不用过多关注它们。
2. 执行autoheader，生成config.h文件
3. 执行autoconf，生成configure文件
4. 执行automake -a，生成Makefile.in文件（每个makefile.am对应一个Makefile.in）
5. 执行./configure
6. 执行三部曲.

至此，我们的项目已经构建完成！！

---

3. 覆盖率分析

在本部分正文展开之前，读者可能需要知道什么是覆盖率，为什么需要覆盖率分析等。这部分的知识可以参考相关文章。

我们利用gcc提供的gcov和Python提供的gcovr两个工具来分析覆盖率。对于单个文件，直接执行

gcov *.c

就可以得到其覆盖率（具体的生成流程，请参考笔者关于覆盖率的博文。）

对于大型的复杂项目，生成覆盖率需要将gcov和automake结合使用。我们直接在编译规则里面完成对覆盖率选项的添加。

即，在上文中每一个Makefile.am文件中添加如下命令：

AM_CFLAGS += -fprofile-arcs -ftest-coverage   ## for c compile
AM_FCFLAGS += -fprofile-arcs -ftest-coverage  ## for fortran compile

再执行:

automake -a
./configure
make

这个时候就会看到在相应的源码路径生成对应的.gcon等文件。然后在每个目录下面执行：

gcov *.c

就可以生成覆盖率文件。

但是，我们这样做，需要手动到每个子路径下面输入这个命令，比较麻烦，借助makefile将其简化。

在每个Makefile.am中添加如下语句：

export MAKEINCLUDE=${top_srcdir}/makeconfig/make.global
include ${MAKEINCLUDE}

cleanall: cleanallsubdirs
	-rm -f *.gcda *.gcov *.gcno

gcov: gcovsubdirs
	@echo "generating base coverage ..."
	gcov -f *.c *.f90

gcovr: gcovrsubdirs
	gcovr -r . --html --html-details -o coverage.html

这个时候makefile会帮我们自动递归相关的文件夹。