[C] c99int(让VC等编译器自动兼容C99的整数类型)V1.02。源码托管到github、添加CMake编译配置文件、使用doxygen规范注释

时间:2023-01-22 15:38:30

新版本——

http://www.cnblogs.com/zyl910/p/zlstdint_v100.html
[C] zlstdint(让VC、TC等编译器自动兼容C99的整数类型)V1.0。支持Turbo C++ 3等DOS下的编译器

作者:zyl910

一、改动简介

  V1.02版的改动如下——

  1. 将源码上传到github.
  2. 调整目录结构.
  3. 添加CMake编译配置文件.
  4. 使用doxygen规范注释.
  5. 修正 __AUTO_STDINT_H_USESYS 误为 _INTTYPES_H_SYS_ 的bug.

二、改动详述

2.1 将源码上传到github

  现在用习惯git了,感觉它很不错。因其支持离线提交等功能,非常适合分布式开发。
  比如有时你突然有了一个灵感,想改进一下自己的代码。可是代码不在身边,改不了。这时有三种办法——
1) 将代码放入U盘,随身携带。缺点是风险高且已损坏,万一U盘坏了或丢了就麻烦了。而且并不是所有场合都能接U盘。
2) 使用带同步功能的网盘。缺点在于网盘是与账号绑定的,一般只能装在自己固定几台电脑上。
3) 将源码托管到某个源码托管网站。使用版本控制工具来管理。

  可见,使用第3种方案是最好的。顺便能利用版本控制工具来管理源码的变更,可以完全不受顾虑的修改。而前2种方案得手动备份,最怕会因激进想法弄乱代码。
  我以前曾尝试过 svn + google code。可是svn是一种集中式版本控制工具,很多操作需要连接到版本库服务器。当连不上版本库服务器,根本没法工作。   后来换成 git+github 就好多了。git支持离线提交,你可以在网络好的时候才将提交推送到版本库服务器上。而且目前访问github比google code容易很多。

  关于git的学习,推荐以下资料——
1) 入门教程推荐 Travis Swicegood的《版本控制之道——使用Git》(http://product.china-pub.com/196738)。
2) 高级教程推荐 蒋鑫的《Git权威指南》(http://product.china-pub.com/194010)。
3) 对于github的,推荐 蒋鑫的《GotGitHub》(http://www.worldhello.net/gotgithub/index.html)。

2.2 调整目录结构

  原先将所有文件都放在一个目录中,显得比较杂乱,不利于管理。
  考虑到本项目是类似函数库的项目,有可能会存在多个示例程序,于是最终决定使用这种目录结构——
docs:用于存放文档相关内容。
examples:存放各个示例程序。
inc:存放第三方头文件。
lib:存放第三方的库。
src:存放代码。本项目头文件与实现文件放在一起,这样容易管理一些。

  本项目不需使用inc、lib目录。

  文件清单——

docs/
examples/
examples/c99inttest/
examples/c99inttest/c99inttest.c
examples/c99inttest/c99inttest.dsp
examples/c99inttest/c99inttest.dsw
examples/c99inttest/c99inttest_2003.sln
examples/c99inttest/c99inttest_2003.vcproj
examples/c99inttest/c99inttest_2005.sln
examples/c99inttest/c99inttest_2005.vcproj
examples/c99inttest/c99inttest_2008.sln
examples/c99inttest/c99inttest_2008.vcproj
examples/c99inttest/c99inttest_2010.sln
examples/c99inttest/c99inttest_2010.vcxproj
examples/c99inttest/c99inttest_2010.vcxproj.filters
examples/c99inttest/c99inttest_2010.vcxproj.user
examples/c99inttest/c99inttest_2012.sln
examples/c99inttest/c99inttest_2012.vcxproj
examples/c99inttest/c99inttest_2012.vcxproj.filters
examples/c99inttest/c99inttest_2012.vcxproj.user
examples/c99inttest/c99inttest_bcb.bpf
examples/c99inttest/c99inttest_bcb.bpr
examples/c99inttest/c99inttest_bcb.res
examples/c99inttest/CMakeLists.txt
examples/c99inttest/makefile
src/
src/auto_inttypes.h
src/auto_stdint.h
c99int.mainpage
c99int_doc.doxygen
c99int_docfull.doxygen
LICENSE
README.md

2.3 Makefile文件的修改

  由于现在调整了目录结构,于是Makefile文件也需要修改。例如对示例程序c99inttest来说,一部分代码在“examples/c99inttest/”目录中,另一部分代码在“src/”目录中。这对Makefile文件的修改带来了一定程度的麻烦。如果没解决好路径问题的话,很容易造成编译失败。
  因可能存在多个示例程序,所以Makefile可以与示例程序放在一起(examples/c99inttest/),这是只需解决“src/”目录问题就行了。
  该问题可分为两个子问题——
1) 如何让编译器(gcc)找到另一路径上的文件?
2) 如何让make程序找到另一路径上的文件?

  第一个问题的解决办法大家都很熟悉,就是使用gcc的“-I”参数来添加include搜索目录。具体对于Makefile文件来说,可以利用CFLAGS变量,如——

CFLAGS += -Wall -I../../src

  第二个问题的解决办法,大家有可能不太熟悉了。办法是使用vpath语句指定依赖文件的搜索路径。因本项目的“src/”目录下面只有头文件,所以只需要在Makefile文件中添加一行——

vpath %.h ../../src

  关于vpath的详细说明,推荐陈皓的《跟我一起写 Makefile》(http://blog.csdn.net/haoel/article/details/2886),具体位于第4篇(http://blog.csdn.net/haoel/article/details/2889)的“四、文件搜寻”节。

  最终c99inttest的Makefile为——

.PHONY : all clean

# flags
CC = gcc
CFLAGS += -Wall -I../../src
#LDFLAGS += -L../../lib
#LIBS += -lglib # args
RELEASE =0
UNICODE =0
BITS =
EXFLAGS = # [args] 生成模式. 0代表debug模式, 1代表release模式. make RELEASE=1.
ifeq ($(RELEASE),0)
# debug
CFLAGS += -g
else
# release
CFLAGS += -O3 -DNDEBUG
//CFLAGS += -O3 -g -DNDEBUG
endif # [args] UNICODE模式. 0代表ansi模式, 1代表unicode模式. make UNICODE=1.
ifeq ($(UNICODE),0)
# ansi
CFLAGS +=
else
# unicode
CFLAGS += -D_UNICODE -DUNICODE
endif # [args] 程序位数. 32代表32位程序, 64代表64位程序, 其他默认. make BITS=32.
ifeq ($(BITS),32)
CFLAGS += -m32
else
ifeq ($(BITS),64)
CFLAGS += -m64
else
endif
endif # [args] 扩展参数. make EXFLAGS="-mavx".
CFLAGS += $(EXFLAGS) # makefile path.
vpath %.h ../../src # files
TARGETS = c99inttest
OBJS = c99inttest.o all : $(TARGETS) c99inttest : $(OBJS)
$(CC) -o $@ $^ $(CFLAGS) $(LDFLAGS) $(LIBS) c99inttest.o : c99inttest.c auto_stdint.h auto_inttypes.h
$(CC) -c $< $(CFLAGS) clean :
$(RM) $(OBJS) $(TARGETS) $(addsuffix .exe,$(TARGETS))

2.4 CMake编译配置文件

  以前我是手工为各个编译器分别建立项目文件的(vc6/2003/2005/2008/2010/2012、bcb6、gcc的makefile),这样管理起来很不方便。当增减文件或调整目录结构时,每一个项目文件都需同步的更改。而且万一用户用的不是这些编译器,那还得自己建立项目文件或编写makefile。

  为了解决上述问题,我决定使用CMake。它是一个比make更高级的编译配置工具,它可以根据不同平台、不同的编译器,生成相应的Makefile或者vcproj项目。官网地址:http://www.cmake.org/

  例如本项目的“examples/c99inttest/CMakeLists.txt”是c99inttest示例程序的编译配置文件。若要根据它来生成项目文件,步骤如下——

Step1 打开CMake,在“Where is source code”文本框中填好CMakeLists.txt所在目录(例如本项目的“examples/c99inttest”目录)
Step2 在“Where to build the binaries”文本框中填好build目录(例如设为本项目的“examples/c99inttest/build”目录)
[C] c99int(让VC等编译器自动兼容C99的整数类型)V1.02。源码托管到github、添加CMake编译配置文件、使用doxygen规范注释

Step3 点击左下角的“Configure”按钮。若目录不存在,它会提示你创建目录,点击“Yes”
[C] c99int(让VC等编译器自动兼容C99的整数类型)V1.02。源码托管到github、添加CMake编译配置文件、使用doxygen规范注释

Step4 随后会弹出选择项目文件类型的对话框。为了方便演示,我这里选择了“Visual Stdio 8 2005”。下面的单选框可以使用默认的“use default native compilers”,点击“Finish”
[C] c99int(让VC等编译器自动兼容C99的整数类型)V1.02。源码托管到github、添加CMake编译配置文件、使用doxygen规范注释

Step5 然后CMark会检查编译器环境,并列出可配置的项目。一般不需修改,直接点击“Generate”生成项目文件
[C] c99int(让VC等编译器自动兼容C99的整数类型)V1.02。源码托管到github、添加CMake编译配置文件、使用doxygen规范注释

生成完毕时,会显示“Generating done”消息。然后打开“build”文件夹,可以发现已经顺利生成了项目文件。
[C] c99int(让VC等编译器自动兼容C99的整数类型)V1.02。源码托管到github、添加CMake编译配置文件、使用doxygen规范注释

  关于CMake的学习,推荐以下资料——
《CMake入门指南》. sinojelly, 2010-05-22. http://www.cnblogs.com/sinojelly/archive/2010/05/22/1741337.html
《cmake 学习笔记(一)》. dbzhang800, 2011-04-10. http://blog.csdn.net/dbzhang800/article/details/6314073

  最终c99inttest的CMakeLists.txt为——

# c99inttest: c99int test for C.
cmake_minimum_required(VERSION 2.6)
project(c99inttest)
include_directories(${PROJECT_SOURCE_DIR}/../../src)
AUX_SOURCE_DIRECTORY(. SRC_LIST)
SET(SRC_LIST ${SRC_LIST} ../../src/auto_stdint.h)
SET(SRC_LIST ${SRC_LIST} ../../src/auto_inttypes.h)
ADD_EXECUTABLE(c99inttest ${SRC_LIST})

2.5 使用doxygen规范注释

  使用doxygen可以很轻松地根据源代码中的注释来生成html、chm、pdf等格式的文档。

  本项目提供了两个doxygen文件——
c99int_doc.doxygen:用于生成接口的文档。针对使用者。
c99int_docfull.doxygen:用于生成接口、实现、示例等内容的详细文档。针对开发者、学习者。

  因开发过程中经常需要生成详细文档以辅助开发。为了减少文档生成时间,我将上述doxygen文件均设为仅生成htm文档。
  当用户需要生成其他格式(chm、pdf等)的文档时,或需要根据graphviz(dot)生成丰富图形的文档时,请自行修改doxygen文件。

  关于doxygen的学习,推荐以下资料——
《Markdown support》. doxygen. http://www.stack.nl/~dimitri/doxygen/manual/markdown.html
《Special Commands》. doxygen. http://www.stack.nl/~dimitri/doxygen/manual/commands.html
《C++标准注释原则 - 基于doxygen的C++注释》. 小"米", 2013-05-09 . http://www.cfanz.cn/index.php?c=article&a=read&id=76718
《Doxygen详细介绍》. 2009-08-06. http://ticktick.blog.51cto.com/823160/188671
《doxygen1.6.1参数》. yongshengfree, 2009-09-08. http://blog.csdn.net/yongshengfree/article/details/4533428
《doxygen+graphviz》. Atela, 2011-10-17. http://www.cnblogs.com/Atela/archive/2011/10/17/2214519.html
《使用doxygen生成中文pdf文档》. zyl910, 2013-06-02. http://www.cnblogs.com/zyl910/archive/2013/06/02/doxygen_pdf_chinese.html
《Objective-C规范注释心得——同时兼容appledoc(docset、html)与doxygen(html、pdf)的文档生成》. zyl910, 2013-06-07. http://www.cnblogs.com/zyl910/archive/2013/06/07/objcdoc.html

源码下载——
https://github.com/zyl910/c99int