构建 C/C++ 项目时添加宏定义

有时候我们希望在构建时能够在命令行添加一些宏定义，改变程序行为。一个典型应用示例是代码里通过检查是否定义了 DEBUG 宏，来决定是否输出调试信息。编译器一般提供命令行选项支持这种做法，例如使用 gcc 时可以在命令行添加 -D 选项，定义一些宏：

gcc -DDEBUG=1 a.c

不过，大型项目一般都需要自动化构建工具，如 GNU Autotools 或者 CMake。使用它们后，我们无法直接修改编译命令，但它们提供了替代方案。对于 Autotools，它可以识别 CPPFLAGS 等环境变量，从而我们可以在命令行上添加宏定义，例如：

CPPFLAGS="-DDEBUG=1" ./configure

此外，我们还可以先 export CPPFLAGS="-DDEBUG=1"，再用 ./configure 命令。注意这里 CPPFLAGS 的 CPP 指的是 C 预处理器 (C Preprocessor)，不是 C++，其中只应该设置 -I、-D、-U 等影响预处理器的选项。Autotools 支持 CFLAGS、CXXFLAGS、LDFLAGS 环境变量，分别用来指定 C 编译链接时、C++ 编译链接时、以及仅在链接时有效的选项。

目前许多项目已经使用 CMake 来构建。CMake 支持 CFLAGS、CXXFLAGS、LDFLAGS 等，但遗憾的是唯独不支持 CPPFLAGS。也就是说，CMake 会无视 CPPFLAGS 环境变量的值。Aron Xu 为此报了一个 BUG，不过因为没人志愿去做，所以一直没有修复。许多人可能会以为，可以用类似 cmake .. -DVAR=VALUE 的方式来添加宏定义，但这是无效的。这样一来，如果想在命令行上指定宏定义，只能复用 CFLAGS 或者 CXXFLAGS 变量。这基本可以工作，因为一般情况下预处理和编译是同一个命令进行的。

CMake 中标准的添加宏定义方法是使用 ADD_DEFINITIONS(-DMACRO)（参考文档），不过这需要修改 CMakeLists.txt 文件。如果想要在命令行上定制宏的开关或取值，那么可以像这里一样，定义一个 CMake 选项：

OPTION(DEFINE_MACRO "Option description" ON) # Enabled by default

然后做一个条件判断：

IF(DEFINE_MACRO)
    ADD_DEFINITIONS(-DMACRO)
ENDIF(DEFINE_MACRO)

之后，就可以用 cmake -DDEFINE_MACRO=OFF .. 调整宏的开关或取值了。

最后值得一提的是，如果代码里已经有了宏定义语句，那么通过命令行修改其取值是不可能的。编译器会警告宏被重复定义，而且生效的是源文件中的定义。想要重新定义，只能随后 #undef 再 #define。这将不得不通过修改代码来实现。

C++ 中作用域受限的枚举类型

本文介绍 C++ 中传统枚举类型存在的作用域不受限等问题，随后列举经典的限定其作用域的做法，最后给出新标准 C++11 下的解决方案。

传统行为

传统的枚举类型在 C 语言中就有，C++ 中行为和 C 中一致，常被用来定义有类型的常量。一个典型的枚举类型定义如下：

enum Color { RED, BLUE };

C++ 发明人 Bjarne Stroustrup 总结这种枚举有如下问题：

• 作用域不受限 (unscoped)，枚举变量的作用域不受限，会暴露给领近的代码作用域（如果在最外层则为全局作用域），容易引起命名冲突。例如如下代码是无法编译通过的：

  enum Color { RED, BLUE };
  enum Feeling { EXCITED, BLUE };

• 会隐式转换为 int。这是 C 中的默认行为，但是和“有类型的常量”的初衷是不符合的。比如上面例子中 EXCITED == RED 会返回真（gcc 编译会有警告），这其实是不合常理的。

• 用来表征枚举变量的实际类型不能明确指定，从而无法支持枚举类型的前向声明。

经典做法

解决作用域不受限带来的命名冲突问题的一个简单方法是，给枚举变量命名时加前缀，如上面例子改成 COLOR_BLUE 以及 FEELING_BLUE。一般说来，为了一致性我们会把所有常量统一加上前缀。但是这样定义枚举变量的代码就显得累赘。C 程序中可能不得不这样做。不过 C++ 程序员恐怕都不喜欢这种方法。替代方案是命名空间：

namespace Color { enum Type { RED, YELLOW, BLUE }; };

这样之后就可以用 Color::Type c = Color::RED; 来定义新的枚举变量了。如果 using namespace Color 后，前缀还可以省去，使得代码简化。不过，因为命名空间是可以随后被扩充内容的，所以它提供的作用域封闭性不高。在大项目中，还是有可能不同人给不同的东西起同样的枚举类型名。

更“有效”的办法是用一个类或结构体来限定其作用域，例如：

struct Color { enum Type { RED, YELLOW, BLUE }; };

定义新变量的方法和上面命名空间的相同。不过这样就不用担心类在别处被修改内容。这里用结构体而非类，一是因为本身希望这些常量可以公开访问，二是因为它只包含数据没有成员函数。

C++11 的枚举类

上面的做法解决了第一个问题，但对于后两个仍无能为力。庆幸的是，C++11 标准中引入了“枚举类”(enum class)，可以较好地解决上述问题。它使用如下语法定义：

enum class Color { RED, BLACK };

可见语法更为简单了。如此一来，定义新变量也得到简化：

Color c = Color::RED;

类限制了其作用域，避免了命名冲突。同时也避免了隐式类型转换。也就是说，枚举类即是作用域受限的 (scoped)，又是强类型的 (strongly typed) 枚举。至于第三个问题，C++11 标准允许指定存储类型：

enum class Color : char { RED, BLUE };

上面例子使用 char 来存储这个枚举类。缺省情况下使用 int。这样枚举就可以进行前向声明了：

enum class Color : char ;   // forward declaration
void foo (Color *p);
// ...
enum class Color : char { RED, BLUE }; // definition

有了前向声明，代码可以更好地组织到不同的文件里，增加程序可读性和可维护性。

更多参考

除了文中链接外，还有如下链接可供参考：

• http://www.cprogramming.com/c++11/c++11-nullptr-strongly-typed-enum-class.html
• http://stackoverflow.com/questions/7090130/enum-in-a-namespace

bladeRF 固件与 FPGA 注记

使用 bladeRF 板卡时我们会遇到两个“镜像”：固件 (firmware) 镜像与 FPGA 镜像。二者是两个不同的概念。但是业界叫法不一，有时候会把二者混为一谈。一般而言，固件指的是嵌入到硬件设备中的软件，存放在只读存储器 (ROM) 或者闪存 (flash) 中，一般不易修改，修改的操作称为“刷新”(flashing)。固件这个名词最初和微代码相关，不过 bladeRF 里源代码是嵌入式 C 程序。FPGA 全名为可编程门阵列，其门电路、寄存器连接可以编程重构，其源程序一般是硬件描述语言 (HDL)，通过综合 (synthesis) 等步骤得到二进制文件。在 bladeRF 板卡上，FPGA 只是一块 Altera 芯片。在没有内置非挥发存储时，FPGA 镜像需要每次上电时重新加载，bladeRF 就是这种情况。所以在拿到板卡时，上面已有固件，但还没有 FPGA 镜像。下面本文会具体说明在使用 bladeRF 时如何刷新固件、加载/更新 FPGA 镜像、以及如何自动加载 FPGA 镜像。注意，有时为了避免混淆，会称 FPGA 镜像为 FPGA 比特流 (bitstream)，或者 FPGA 配置（因为它就是配置了门电路等组件的连接）。

刷新固件

注意：刷新固件前请先取消 FPGA 自动加载，以避免可能的冲突。FPGA 自动加载的细节参见下文。

Nuand 官方提供固件的源码，我们可以自行编译，不过这需要一套嵌入式开发工具链。Nuand 也提供构建好的固件镜像，可以直接下载使用。要刷新固件，只需在命令行执行：

bladeRF-cli -f bladeRF_fw_vX.Y.Z.img -v verbose

其中 X.Y.Z 为具体的版本号。命令完成后，需要断电重启了 bladeRF。然后可以用 bladeRF-cli 工具检查：

$ bladeRF-cli -e version

  bladeRF-cli version:        0.11.1-git-c631100
  libbladeRF version:         0.16.2-git-c631100

  Firmware version:           1.7.1-git-ca697ee
  FPGA version:               Unknown (FPGA not loaded)

看下其中 Firmware version（固件版本）是否更新。

事实上，还有另外一种刷新固件的方法，是通过进入设备的启动加载 (Bootloader) 模式（类似 Android 的 Recovery），输入一些命令完成的。不过这种方式步骤繁琐，一般不推荐使用，建议在上述简单方法遇到错误时考虑采用。具体步骤参加维基。

加载 FPGA 镜像

注意到上面的示例中，FPGA version（FPGA 版本）显示为 Unknown（未知），FPGA 未加载。目前 bladeRF 使用两种 FPGA。要加载正确的 FPGA 镜像，首先需要确定手头 bladeRF 板卡的 FPGA 尺寸。它可以根据当初购买的价格判断，但更靠谱的方法是使用命令行查看：

$ bladeRF-cli -i
bladeRF> info

  Serial #:                 4f977f01eec48f5068c2ee3aeba41ba9
  VCTCXO DAC calibration:   0x8b63
  FPGA size:                40 KLE
  FPGA loaded:              yes
  USB bus:                  4
  USB address:              5
  USB speed:                SuperSpeed
  Backend:                  libusb
  Instance:                 0

交互模式下用 info 命令，或者直接在命令行下 bladeRF-cli -e info，在输出中寻找 FPGA size，就可以看到 FPGA 尺寸信息。这里示例显示板卡使用 40 KLE FPGA。事实上，FPGA 尺寸还可以通过查看 FPGA 芯片上的 EP4CExxxF23C8N 字样中 xxx 的部分来获得。

Nuand 官方提供了预先构建的 FPGA 镜像，免除用户手工编译之苦。40 KLE FPGA 对应 hostedx40.rbf 文件，以此类推。要加载 FPGA 镜像，只需使用命令 bladeRF-cli -l /path/to/fpga/file，或者交互模式下 load fpga /path/to/fpga/file，其中 /path/to/fpga/file 为 FPGA 镜像所在路径。FPGA 镜像成功加载后，板卡上的三个 LED 灯会亮起，交互模式下 version 命令可以看到 FPGA 版本不再是未知。

不过，正如前文所说，每次重新加电后，FPGA 镜像都需要重新加载。下面说下如何自动加载 FPGA 镜像。

自动加载 FPGA 镜像

bladeRF 维基上提供了两种自动加载 FPGA 镜像的方法。第一种方法基于主机软件，libbladeRF 在打开设备时，会在如下目录自动搜索合适的 FPGA 镜像：

• $HOME/.config/Nuand/bladeRF/
• $HOME/.Nuand/bladeRF/
• /etc/Nuand/bladeRF/
• /usr/share/Nuand/bladeRF/

只需将下载的 FPGA 镜像文件放在上述目录之一（没有可以新建之），即可实现 FPGA 镜像的自动加载。

另一种方式是将 FPGA 镜像写入设备的 SPI 闪存。这种方式的好处是写入后就不再依赖主机，从而可以实现脱机运行。不过这种方式比较慢，加载 x40 镜像需要大约 4 秒钟。注意绝对不要在加载完成，三个 LED 灯亮起前试图使用设备。要使用这种方式，需要执行下面命令：

bladeRF-cli -L /path/to/fpga/file

一般说来，如果没有脱机工作的需求，还是推荐第一种自动加载方法。

前面提到，刷新固件时最好取消自动加载。对于第一种方法，只需把 FPGA 镜像文件临时移走。第二种方法，则需要执行命令 bladeRF-cli -L X，以擦除写入的 FPGA 镜像。

致谢

本工作由星天科技赞助。

Fedora 上搭建 bladeRF 环境

bladeRF 维基上介绍了在 Linux 系统上搭建 bladeRF 环境的步骤，不过原文是英文的，另外其中一些具体选择不尽合理。本文以 Fedora 系统为示例，提供一个中文版的 bladeRF 环境搭建指南，并着重介绍和维基上的不同点。比较可能有一定的时效性，但一些原则应该足够通用。本文的比较基准是当前的维基版本。

安装依赖

维基上建议安装 “Development Tools” “Development Libraries” 两个软件包组，但我们只需要其中的一部分软件包，其中有些可能已经安装过了，而像 cvs 等并不必须。如果你像我一样有“洁癖”，不希望安装不需要的软件包，那么可以用如下的命令安装必须的依赖（未严格验证，在我这里绝大多数包都在之前安装过了）：

sudo yum install git doxygen gettext glibc-devel ncurses-devel readline-devel zlib-devel boost-devel
sudo yum install libusbx libusbx-devel cmake wget gcc-c++

注意其中是 libusbx 而非 libusb，后者是 0.x 系列的版本，而非 1.x 系列。Debian/Ubuntu 系的用户会注意到软件包命名上的差异 (devel 而非 dev)。

维基上推荐安装 libtecla，以增强 bladeRF-cli 交互模式的编辑功能。不过 Fedora 软件源里目前还没有这个包，所以需要手动下载，解压缩，使用经典的 ./configure; make; sudo make install 三部曲安装。

构建 bladeRF

在终端下进入打算用来放置 bladeRF 源码的目录，用 git 将 bladeRF 的源码库克隆下来：

cd /path/to/bladeRF/directory
git clone https://github.com/Nuand/bladeRF.git

切换到源码目录中的 host 目录，创建一个 build 目录用来存放构建过程的中间文件。这种使用单独的构建目录的方式称为树外构建 (out of tree build)，相对于直接在源码目录构建，好处在于生成的中间文件不会分散在源码目录里，方便清理，另外可以用多个构建目录构建出互不干扰的不同参数下的版本。之后切换到构建目录，然后就是标准的 cmake ..; make; sudo make install 三部曲了。注意这里 cmake 时启用了 INSTALL_UDEV_RULES 宏，使得安装时把 udev 规则文件也安装到系统中。

cd bladeRF/host/
mkdir build
cd build
cmake -DINSTALL_UDEV_RULES=ON ../
make
sudo make install

很遗憾的是这里安装的 udev 规则文件使用了 plugdev 群组，不是 Fedora 下的标准做法。可以参考之前的博文修改 udev 规则文件。

为了让新安装的 bladeRF 库文件可以被二进制文件使用，我们需要用 ldconfig 刷新系统动态库的缓存。上面的构建过程会将 bladeRF 安装到 /usr/local 下，而其中的库文件目录 /usr/local/lib{,64} 不在 ldconfig 的默认搜索路径里。所以我们可以将它们添加到 /etc/ld.so.conf 里。添加之后文件内容如下：

/usr/local/lib
/usr/local/lib64
include ld.so.conf.d/*.conf

之后，用 sudo ldconfig 刷新缓存即可。可以用 ldd /usr/local/bin/bladeRF-cli 命令检查 bladeRF 库文件是否被找到。连上 bladeRF 设备，用 bladeRF-cli -p 命令看下是否能够发现设备。更多操作见于另一个维基页。

构建 GNU Radio 与 gr-osmosdr

通过上述步骤，就可以操作 bladeRF 板卡了。但是，要想便捷地为 bladeRF 开发软件无线电应用，最好再构建一下 GNU Radio 和 gr-osmosdr。GNU Radio 是一个开源的软件无线电开发平台，提供众多的信号处理模块和简单易用的图形界面开发环境。gr-osmosdr 适配 GNU Radio，为众多硬件板卡（除了 bladeRF 之外还有 HackRF 等）提供一个统一的软件接口。

GNU Radio 依赖比较多，编译安装相对麻烦，一般推荐使用 build-gnuradio 脚本。但是因为其中涉及到从网络下载诸多软件以及编译安装，效率受网速和电脑硬件性能限制，耗时较长。另外，脚本的健壮性不高，所以很容易中途退出。这个脚本很长，但实际上是把整个构建过程划分为几个步骤，放在几个函数里先后执行的。我建议阅读这个 Shell 脚本，每次运行其中的一步或几步，必要时手动完成一些配置。对于新手，这会是一个很好的通过阅读代码学习 Shell 编程的机会。

具体的构建步骤可以在维基或这里找到，这里就不再赘述。只是提几点注意事项：

• 如果你像我一样，除了 bladeRF 之外，还会使用 Ettus 公司的 USRP 系列设备，那么记得先构建 UHD，然后构建 GNU Radio。
• build-gnuradio 脚本在 cmake 时，有时用了树外构建，但有时又没用。建议始终用树外构建。
• 编译 GNU Radio 时，并行 make （make -j N 其中 N 大于 1）时有时会编译失败（竞态条件？），直接 make 就可以正常编译通过，虽然速度会慢很多。什么？make 也会出错？那考虑换一个 git 提交重新编译，并向上游报 BUG 吧。

构建成功 GNU Radio 后，构建 gr-osmosdr 就显得小菜一碟了，标准的 cmake 构建三部曲，项目不大，编译过程也能很快完成。

全部构建完成后，可以使用如下命令用 bladeRF 看一下频谱，检验是否大功告成。其中 FPGA 映像可以从 Nuand 网站下载。此外，最新固件也可以从官网下载。

osmocom_fft -a bladerf=0,fpga=<your FPGA image> -s 2000000 -f 446000000

致谢

本工作由星天科技赞助。

connect6-ng 连接 SVN 历史和 Git 历史

我的 connect6-ng 是在 connect6 的基础上进行的。原项目使用 SVN 做版本控制，但我更喜欢使用 Git。所以我在开始 connect6-ng 时先检出了 SVN 仓库里的最新版本然后取出其中源代码初始化了 Git 仓库，并没有继续 SVN 历史。

董渊老师建议我能把两段历史连接起来，以体现出项目的延续性。老师还帮忙使用 git-svn 在 Ubuntu 9.10 下将 connect6 项目的 SVN 历史转换到了 Git 仓库下：

mkdir connect6.git
cd connect6.git/
git-svn init http://connect6.googlecode.com/svn/ --no-metadata
git config svn.authorsfile ../authors.txt
git-svn fetch
git log
cd ..
tar -zcvf connect6.git.tgz connect6.git/

其中authors.txt的内容为：

qq280833822 = CHEN Shuang <qq280833822@gmail.com>
wanglei     = WANG Lei    <leopardguo25@gmail.com>

我收到 connect6.git.tgz 后在连接两段历史前，对前一段历史记录做了一些更改：使用 git filter-branch 删除了仓库里的 *.class 文件、/trunk/connect6.jar 文件，因为我觉得这些中间文件或目标文件放在仓库里意义不大。另外，我又将 trunk 目录做成了仓库的根目录，这和后面我的仓库更接近。处理后的仓库目录我命名为 connect6-shrinked/。

参考 stackoverflow 中这个问题的回答，我使用其中的第三种方法(refs/replace/) 将 SVN 仓库历史转换成的 git 历史添加在了 connect6-ng 提交历史的前面，连上了两段历史。不太详细的步骤如下：

切换到新项目 connect6-ng 的顶层目录，把 connect6-shrinked 加为一个远程仓库，命名为 history：

$ git remote add history file:///path/to/connect6-shrinked/

然后找出 connect6-ng 项目最初的提交(Initial commit)的 SHA1 值，保存到 $TAIL 变量中：

$ TAIL=$(git rev-list --topo-order master | tail -n 1)

接着找出要导入历史的旧项目的最近的一次提交，保存到 $TOP 变量中：

$ TOP=$(git rev-parse --verify history^0)

然后读取 $TAIL 这个 commit 对象的内容：

$ git cat-file commit $TAIL > TAIL_COMMIT

手工编辑 TAIL_COMMIT 这个文件，加入一行 parent $TOP（其中 $TOP 换成对应的 SHA-1 值），这使得新项目的初始提交有了旧项目的顶部作为父提交。将新的 TAIL_COMMIT 写入仓库：

$ NEW_TAIL=$(git hash-object -t commit -w TAIL_COMMIT)

最后使用 git replace：

$ git replace $TAIL $NEW_TAIL

这样就连接好了两段历史记录，可以用 git log 等查看。

要把合并后的历史 push 出去，需要在自己仓库 .git/config 文件中对应 remote 部分加一行：

push = +refs/replace/*:refs/replace/*

在合并两段历史之前已经从 connect6-ng 远程仓库 clone 了代码仓库的同学，如果不做修改，还是只能看到较新的一段历史。要想看到旧的SVN导出的历史，需要修改自己的 .git/config 里 origin 部分（或者其他指向 connect6-ng 远程仓库的 remote 分支名）添加一行：

fetch = +refs/replace/*:refs/replace/*

这样之后 git fetch 和 git pull 就可以拉取 refs/replace/ 下的后来添加的历史了。

附注：本文参考了董渊老师和我的邮件、stackoverflow 上的回答等，一并感谢。