September 24th, 2016

在上一篇概念:GNU构建系统和Autotool,我对GNU构建系统从用户视角和开发者视角分别进行了阐述。本篇从我的实践总结的角度,并阐述如何从头开始规划一个基于GNU构建系统的项目。事实上,随着开发者对跨平台认知的深入和完善,才能逐渐掌握GNU构建。注意:本文的例子不依赖于任何IDE和编辑器。这样读者可以从根本上认识到每个文件的作用。

安装autotools

需要安装的工具包括autoconf、automake、libtool。

目录结构规划

首先,我们需要规划项目的目录结构。假设,我们的项目叫gnu-build。设想如下目录结构:

gnu-build
 |---build(用于编译)
 |---src
      |---common
           |---Makefile.am
           |---pool.c
           |---alloc.c
           |---list.c
           |...
      |---core
           |---Makefile.am
           |---main.c
           |...
      |---test
           |---Makefile.am
           |---test.c
           |...
      |---Makefile.am
 |---configure.ac
 |---Makefile.am
 |---.gitignore

从上面的目录结构可以看出:

  1. 根目录有一个configure.ac,这是构建系统的核心文件之一,描述整个构建的依赖和输出,是configure脚本的原型。
  2. 每个目录(包括根目录)都有一个Makefile.am,这些文件是生成Makefile的主要来源。使用Makefile.am的优点是可以结合configure.ac、比手动编写Makefile方便很多。
  3. src目录下放置源代码,源代码被分成commoncoretestcommon用来实现一些可重用的代码,比如通用数据结构,内存管理,异常的封装;core用来放置直接编译成可执行程序的代码,比如main.c等;test用于编写单元测试程序。
  4. build目录用于存放编译过程中的临时文件和编译得到了目标文件。一般我们总是cdbuild目录中,并执行../configureconfigure,并在build目录下make。这样的话,由configure产生的文件不会污染源码空间。我们需要做的只是在.gitignore中添加build/

在使用autoreconf的过程中,还将在各个目录下生成其他的文件(尤其是根目录)。现在我们只需要创建上述必要文件。

configure.ac可以通过在根目录下执行autoscan程序生成。如果你已经有一些代码了,使用autoscan生成configure.ac是个不错的开始。

configure.ac的基本编写

通用宏

每个configure.ac都需要如下两行。分别说明需要的autoconf的最低版本,以及程序的包名、版本、bug反馈邮件地址。

AC_PREREQ(2.59)
AC_INIT([gnu-build], [1.0], [support@gnubuild.org])

configure.ac通篇几乎都是采用这种类似函数调用的语法编写,这些称为的语句,会被autoconf工具识别,并展开成相应的shell脚本,最终成为configure脚本。除此之外,也可以混合地直接编写shell脚本。autoconf预置了很多实用的宏,可以减少工作量,后面你将看到的价值。

可以直接编写shell脚本,但是推荐尽量使用宏。因为shell程序有很多种(sh,bash,ksh,csh…),想要写出可移植的shell并不是件容易的事情。

接着,通常使用AC_CONFIG_SRCDIR来定位一个源代码文件,如此一来,autoconf程序会检查该文件是否存在,以确保autoconf的工作目录的正确性。这里,我们指向src/core/main.c

AC_CONFIG_SRCDIR([src/core/main.c])

定义输出的宏

一般来说,都会编写一个header输出定义。这是我们用到的第一个输出指令。输出指令告诉configure,需要生成哪些文件。AC_CONFIG_HEADERS的含义是在指定的目录生成.h,一般叫做config.h,你也可以指定其他名字。

AC_CONFIG_HEADERS([src/common/config.h])

那么这个config.h究竟有什么用呢?回忆一下,configure程序的主要目的是检测目标平台的软硬件环境,从而在实际调用make命令编译程序前,对编译工作进行一个预先的配置,这里的配置落实到底,主要就是生成Makefileconfig.h

Makefile.am --> Makefile.in --> Makefile
                             |
                           configure*
                             |
                config.h.in --> config.h

那么我们的程序必需要通过某种方式,得知环境的不同,从而通过预编译做出响应。这里的响应主要分两块:

  1. 对于源代码而言,通过config.h中的宏定义,来改变编译行为。
  2. 对于Makefile.am而言,通过configure.ac导出的变量,来动态改变Makefile。

在后面的叙述中,可以通过代码体会这两点。所以这里,为了让我们的源码有能力根据环境来改变编译行为,生成config.h通常是必要的。

另一个输出宏是AC_CONFIG_FILES,针对这个例子,告诉autoconf,我们需要输出Makefile文件:

AC_CONFIG_FILES([Makefile
                 src/Makefile
                 src/core/Makefile
                 src/common/Makefile
                 src/test/Makefile
                 ])
AC_OUTPUT

注意到每个目录都需要由对应的Makefile文件,这是automake多目录组织Makefile的通用做法。后面会讲到如何编写各个目录下的Makefile.am

AC_CONFIG_FILES一般跟AC_OUTPUT一起写在configure.ac的最后部分。

automake声明

为了配合automake,需要用AM_INIT_AUTOMAKE初始化automake:

AM_INIT_AUTOMAKE([foreign])

这里foreign是个可选项,设置foreign跟调用automake --foreign是等价的,前一篇有讲到。

libtool声明

配合使用libtool,需要加入LT_INIT,这样autoreconf会自动调用libtoolize

LT_INIT

编译器检查

configure可以帮助我们检查编译和安装过程中需要的系统工具是否存在。一般在进行其他检查前,先做此类检查。例如下面是一些常用的检查:

# 声明语言为C
AC_LANG(C)

# 检查cc
AC_PROG_CC

# 检查预编译器
AC_PROG_CXX

# 检查ranlib
AC_PROG_RANLIB

# 检查lex程序,gnu下通常叫flex
AC_PROG_LEX

# 检查yacc,gnu下通常叫bison
AC_PROG_YACC

# 检查sed
AC_PROG_SED

# 检查install程序
AC_PROG_INSTALL

# 检查ln -s
AC_PROG_LN_S

针对这个例子我们只需要检查cccxx就可以了。

Makefile.am的基本编写

Makefile.am文件是一种更高层次的Makefile,抽象程度更高,比Makefile更容易编写,除了兼容Makefile语法外,通常只需包含一些变量定义即可。automake程序负责解析,并生成Makefile.in,而Makefile.in从表现上与Makefile已经十分接近,只差变量替换了。configure脚本执行后,Makefile.in将最终转变成Makefile。

子目录引用

在本例中每个目录下都有Makefile.am。根目录的Makefile.am生成的Makefile将是make程序的默认入口,但是根目录实际上并不包含任何需要构建的文件。对于需要引用子目录的Makefile来构建的时候,使用SUBDIRS罗列包含其他Makefile.am的子目录。因此,对于根目录的Makefile.am只需要写一行:

SUBDIRS = src

同理,src目录下的Makefile.am只需要

SUBDIRS = common src test

定义目标

对于包含有源代码文件的目录。首先,我们需要定义编译的目标,目标可能是库文件或可执行文件,目标又分为需要安装和不需要安装两种。例如对于common目录 下的源代码,我们希望生成一个不需要安装的库文件(使用libtool),因为这个库文件只在本项目内使用,那么common/Makefile.am应当这样写:

noinst_LTLIBRARIES = libcommon.la
libcommon_la_SOURCES = pool.c alloc.c list.c

定义了一个目标libcommon.la。由于使用libtool,所以库文件必须以lib开头,后缀为.la

目标的基本格式为where_PRIMARY = targets ... where表示安装位置,可选择bin、lib、noinst、check(make check时构建),还可以自定义。我们着重讨论前三种:

  • bin:表示安装到bindir目录下,这种情况下会编译出动态库
  • lib:表示安装到libdir目录下,这种情况下会编译出动态库
  • noinst:表示不安装,这种情况下会编译出静态库,在其他目标引用该目标时将进行静态链接

PRIMARY可以是PROGRAMS LIBRARIES LTLIBRARIES HEADERS SCRIPTS DATA。着重讨论前三种:

  • PROGRAMS:表示目标是可执行文件
  • LIBRARIES:表示目标是库文件,通过后缀来区别静态库或动态库
  • LTLIBRARIES:表示是libtool库文件,统一后缀为.la

与Makefile的思想一样,目标的生成需要定义来源,通常目标是有一些源程序文件得到的。Makefile.am中只需定义xxx_SOURCES,后面跟随构建xxx这个目标需要的源代码文件列表即可。注意到xxx是目标的名字,并且.字符需要使用_代替。

定义编译选项

core目录下需要生成可执行目标,但是在链接时,需要用到libcommon.la,此时core/Makefile.am可以写成

bin_PROGRAMS = gnu-build
GNU_BUILD_SOURCES = main.c
GNU_BUILD_LIBADD = $(top_builddir)/src/common/libcommon.la

这里多了一行GNU_BUILD_LIBADDtarget_LIBADD的形式表示为target添加库文件的引用,这种引用是静态的还是动态的取决于引用的库文件是否支持动态库,如果支持动态库,libtool优先采用动态链接。而由于libcommon.la指定为noinst,所以不可能以动态链接的形式存在,这里必然是静态链接。

$(top_builddir)引用的是make发生时的工作目录,上文提到,我们将在build目录下进行构建,那么库文件会生成在build目录下,而不是源码根目录下,所以$(top_builddir)实际就是gnu-build/build目录,而这样可以很好的支持在另一个目录中编译程序。与之相对应的是$(top_srcdir)对应的是源码的根目录,即gnu-build目录。

还有多个可以配置用于改变编译和链接选项的配置项:

  • xxx_LDADD:为链接器增加参数,一般用于第三方库的引用。比如-L -l
  • xxx_LIBADD:声明库文件引用,一般对于本项目中的库文件引用采用这种形式。
  • xxx_LDFLAG:链接器选项
  • xxx_CFLAGS:c编译选项,如-D -I
  • xxx_CPPFLAGS:预编译选项
  • xxx_CXXFLAGS: c++编译选项

如果xxx是AM,则表示全局target都采用这个选项。

安装路径

刚刚提到的bindirlibdir是configure目录体系下的,类似的路径还有:

prefix				/usr/local
exec-prefix			{prefix}
bindir				{exec-prefix}/bin
libdir				{exec-prefix}/lib
includedir			{prefix}/include
datarootdir			{prefix}/share
datadir 			{datarootdir}
mandir				{datarootdir}/man
infodir				{datarootdir}/info
...

可以看到prefix在这里的地位是一个顶层的路径,其他的路径直接或间接与之有关。而prefix的默认值为/usr/local。所以可执行程序默认总是安装在/usr/local/bin。用户总是可以在调用configure脚本时通过--prefix指定prefix。更详细的路径列表可以通过./configure --help了解。

开始构建

填充一些源代码后,就可以使用autoreconf了,只需要在根目录下执行autoreconf --install即可。

[root@xxx gnu-build]# autoreconf --install

前一篇中,对autoreconf的整个过程和产生的文件做了详尽的分析和阐述,读者也应该十分清楚这里将得到若干Makefile.incommon/config.h.in文件。

如果这个过程顺利的话,就可以在build目录下构建了:

# cd build
# ../configure
# make

这里configure后,会在build目录下生成对应位置的Makefile和common/config.h文件,而不是生成在源码目录中从而污染源码

至此,你已经完成了一个项目的基本构建框架,后面的事情,就是逐步完善构建对环境的依赖。

在configure.ac中配置环境检查

autoconf为程序员提供的最为重要的功能就是提供了一种便捷、稳定、可移植的方式,让程序能在特定目标平台和目标环境上安全的编译运行程序。不过,autoconf只是提供了一些宏,用来简化环境检查。而究竟要检查些什么,如何合理的利用这些宏完成目的,依旧是需要大量的积累的。笔者在这里对一些常用的宏进行一些介绍。

可执行文件检查

有些第三方库在安装到系统后,会附带安装若干可执行程序,并可在环境变量的支持下直接运行。有时,我们通过检查此类可执行程序是否存在,来初步判断该第三方库是否已经安装在目标平台。其中一种常用的宏是AC_CHECK_PROGS

# 声明一个变量PERL,检查perl程序是否存在并可执行
# 如果不存在$PERL变量将是NOTFOUND,如果存在$PERL变量将是perl
AC_CHECK_PROGS([PERL], [perl], [NOTFOUND])

# 声明一个变量TAR,检查tar和gtar程序是否存在并可执行
# 如果不存在$TAR变量将是:,如果存在,第一个可用的程序名将赋值给$TAR
AC_CHECK_PROGS([TAR], [tar gtar], [:])

GNU软件有一种利用pkg-config,来进行自描述的机制。即可以通过注册软件自身(通常提供库文件的软件),让pkg-config能够返回库文件的安装路径等信息,以便以一种统一的方式提供给调用程序。有些库软件附带有独立的config程序,比如pcre-configapr-1-config。如果对这类库提供软件需要检查依赖和编译链接,通常可以通过AC_CHECK_PROGS来检查config程序,从而得到编译链接选项。

打印消息宏

打印消息可以作为调试手段,同时也可以在用户在configure过程中,给予提示信息。

# error将终止configure
AC_MSG_ERROR([zlib is required])

# warn不会终止configure
AC_MSG_WARN([zlib is not found, xxx will not be support.])

注意到AC_MSG_ERROR将中断configure的执行,一般用于必需的编译环境无法满足时。

库检查宏

检查某库是否存在是最重要的功能,因为我们程序往往需要这些库,甚至是库中的某个函数的支持才能正确的运行。

使用AC_CHECK_LIB检查库以及其中的函数是否存在,该宏的原型为:

AC_CHECK_LIB (library, function, [action-if-found],[action-if-not-found], [other-libraries])
  • library:需要检查的库名,无需lib前缀,比如为了检查libssl是否存在,这里需要传入ssl
  • function:这个库中的某个函数名
  • action-if-found:如果找到执行某个动作,这个动作可以是另一个宏,可以是shell脚本。如果不指定这个参数,默认在LIBS环境变量中增加-l选项,从而将在链接过程中将这个库链接进来。比如-lssl。并且在config.h中定义一个宏HAVE_LIBlibrary,例如HAVE_LIBSSL。我们的代码可以根据这个宏得知当前编译环境是否提供libssl
  • action-if-not-found:如果找不到则执行某个动作

通过下面几个宏可以检查系统是否包含某些头文件,以及是否支持某些函数:

  • AC_CHECK_FUNCS:检查是否支持某些函数。作为检查的副作用,在config.h中会定义一个宏HAVE_funcs(全大写)
  • AC_CHECK_HEADERS:检查是否支持某些头文件。作为检查的副作用,在config.h中会定义一个宏HAVE_header_H(全大写)

来举个例子,大家知道libiconv是一个可以在不同字符集间进行转化的库,如果我们的程序希望能够在不同字符集间转化的字符串的话,可以使用该库。然而,在不同平台上,该库的移植方式有些区别。

gnu的标准c库(glibc)在很早的时候就把libiconv集成到了glibc中,因此在linux上可以无需额外的库支持即可使用iconv。然而,在非linux上,很可能需要额外的libiconv库。那么如果在非linux的平台上编写可移植的程序,可以参考如下的宏组合:

AC_CHECK_FUNCS(iconv_open, HAVE_ICONV=yes, [])
if test "x$HAVE_ICONV" = "xyes"; then
     AC_CHECK_HEADERS(langinfo.h, [], AC_MSG_WARN([langinfo.h not found]))
     AC_CHECK_FUNCS([nl_langinfo], [], [AC_MSG_WARN([nl_langinfo not found])])
else
    AC_CHECK_LIB([iconv], [libiconv_open], [HAVE_ICONV=yes], [AC_MSG_WARN([no iconv found, will not build xm_charconv])])
    if test "x$HAVE_ICONV" = "xyes"; then
        LIBICONV="-liconv"
        SAVED_LIBS=$LIBS
    	LIBS="$LIBS $LIBICONV"
    	AC_CHECK_HEADERS(langinfo.h, 
                     AC_CHECK_FUNCS([nl_langinfo], [], [AC_MSG_ERROR([nl_langinfo not found in your libiconv])]), 
                     AC_CHECK_FUNCS([locale_charset], [], [AC_MSG_ERROR([no langinfo.h nor locale_charset found in libiconv])]))
    	LIBS=$SAVED_LIBS
    fi
fi

在这个例子中,我们可以看到许多技巧。我们来逐一解读一下:

  1. 首先通过AC_CHECK_FUNCS检查iconv_open函数,如果在Linux平台上,通常该函数可以在没有任何额外库的情况下提供,所以HAVE_ICONV这个临时变量将设置为yes
  2. 接着通过shell的if测试判断临时变量HAVE_ICONV是否为yes
  3. 如果已经检测到iconv,那么进一步检查langinfo.h头文件和nl_langinfo函数,无论是否能检查通过,由于使用了AC_MSG_WARN,所以configure并不会失败退出,最多只是提示用户警告。更重要的是,我们可以通过config.h中的宏,在代码中得知是否支持头文件和函数,从而调整编译分支。具体的在这个例子中这两个宏分别为HAVE_LANGINFO_HHAVE_NL_LANGINFO
  4. 在非linux下可能需要额外的libiconv库,所以在else分支中,立刻采用AC_CHECK_LIB检测iconv库,以及其中的libiconv_open函数。同样的,如果存在,HAVE_ICONV这个临时变量将设置为yes
  5. 在接下来的if测试中,使用到了$LIBS变量,这是一个由编译器支持的变量,表示在链接阶段的额外库参数。当我们检测到libiconv后,就给这个变量临时地添加-liconv。这样接下来的AC_CHECK_FUNCS时,可以利用$LIBS在额外的库中查找函数。
  6. 检查langinfo.h头文件,如果存在则再检查nl_langinfo函数;如果不存在,则检查locale_charset函数。从逻辑上看,要么langinfo.hnl_langinfo同时存在,要么有locale_charset函数,否则就终止configure。
  7. 最后重置$LIBS变量。

变量导出

configure脚本的检测结果应当有两个主要出口,一是config.h,它帮助我们在源码中创建编译分支;二是Makefile.am,我们可以在Makefile.am中基于这些导出的变量,改变构建方式。

有些宏可以自动帮我们导出到config.h,关于这一点上文已经有所阐述了。而希望导出到Makefile.am则需要我们自己手动调用相关宏。这里主要有两个宏:

  • AC_SUBST:将一个临时变量,导出到Makefile.am。实际是在Makefile.in中声明一个变量,并且在生成Makefile时,由configure脚本对变量的值进行替换。
  • AM_CONDITIONAL:由automake引入,可进行一个条件测试,从而决定是否导出变量。

例如,针对上面iconv的例子,我们有个临时变量HAVE_ICONV,如果iconv在当前平台可用,此时HAVE_ICONV将会是yes。所以可以使用AM_CONDITIONAL导出变量:

AM_CONDITIONAL([HAVE_ICONV], [test x$HAVE_ICONV != x])

或者无论如何都导出HAVE_ICONV

AC_SUBST(HAVE_ICONV)

在Makefile.am中,我们可以对变量进行引用,这样xm_charconv.la就将在HAVE_ICONV导出的情况下构建:

if HAVE_ICONV
  xm_charconv_LTLIBRARIES = xm_charconv.la
  ...
endif

提供额外用户参数支持

很多软件都支持用户在configure阶段,可通过--with-xxx --enable-xxx等命令行选项对软件进行模块配置或编译配置。以--with-xxx为例,我们需要AC_ARG_WITH宏:

AC_ARG_WITH(configfile,
  [  --with-configfile=FILE   default config file to use],
  [ ZZ_CONFIGFILE="$withval"],
  [ ZZ_CONFIGFILE="${sysconfdir}/zz.conf"]
  )

AC_SUBST(ZZ_CONFIGFILE)

FILE定义该参数的值应当是一个文件路径(DIR要求一个目录路径),该宏需要提供一个默认值,这个例子中是${sysconfdir}/zz.conf${sysconfdir}引用了${prefix}/etc,而$withval从命令行中引用--with-configfile的值。

最后我们通过AC_SUBST导出一个临时变量。

上一节提到,导出的临时变量可以在Makefile.am中引用,所以我们可以在Makefile.am中通过-D传递给代码,从而在代码中通过宏来引用:

CFLAGS	+= -DCONFIGFILE=\"$(ZZ_CONFIGFILE)\" 

总结

本文以一个例子,一步步使用GNU构建系统来创建一个项目,并介绍了一些常用的检测宏。事实上,autotool还有很多宏,甚至可以自定义宏。能否合理利用autotool取决于程序员对可移植性这个问题的经验和理解。


1块2块也是钱,小额赞助