GDAL源码剖析（三）之Swig编译和帮助文档生成

一、Swig编译

1、Swig介绍

SWIG全称是Simplified Wrapper and Interface Generator，官方网站：http://www.swig.org/。SWIG是个帮助使用C或者C++编写的软件能与其它各种高级编程语言进行嵌入联接的开发工具。SWIG能应用于各种不同类型的语言包括常用脚本编译语言例如Perl, PHP, Python, Tcl, Ruby and PHP。支持语言列表中也包括非脚本编译语言，例如C#, Common Lisp (CLISP, Allegro CL, CFFI, UFFI), Java, Modula-3, OCAML以及R，甚至是编译器或者汇编的计划应用（Guile, MzScheme, Chicken）。SWIG普遍应用于创建高级语言解析或汇编程序环境，用户接口，作为一种用来测试C/C++或进行原型设计的工具。SWIG还能够导出XML或Lisp s-expressions格式的解析树。SWIG可以被自由使用，发布，修改用于商业或非商业中。[摘自SWIG官网http://www.swig.org/translations/chinese/index.html]。
下载安装Swig的时候注意下载Swigwin（我下的是swigwin-2.0.4.zip），不要下载源代码，否则不能在windwos下用。下载后解压，将swigwin-2.0.4的解压目录也添加到环境变量Path中去，否则会出现一些些该配置文件的麻烦。检验swig是否成功设置到环境变量Path中的最简单的方式就是在运行中输入swig后回车，如果提示windows找不到swig，那么说明没有设置成功；如果出现一个黑屏一闪而过，那么说明你设置成功了。

2、编译C#版本GDAL

首先，打开nmake.opt文件，找到SWIG=swig.exe这一句，假如没有将swig的目录添加到环境变量中，那么将这句后面的swig.exe修改为swig.exe的全路径，如F:\Work\3rdPart\swigwin-2.0.4\swig.exe。如果设置了环境变量，那么就不需要进行修改了。

然后按照第二篇中的使用cmd命令编译GDAL的方式来进行编译，打开“Visual Studio 2008命令提示”并定位到GDAL源代码目录，然后依次执行下面三行命令：

	nmake /f makefile.vc
	nmake /f makefile.vc install
	nmake /f makefile.vc devinstall

执行完之后会在GDAL_HOME的目录下生成编译好的dll和exe文件以及include、lib等文件夹。接下来，使用cd命令，进入swig\csharp文件夹中：

	cd swig\csharp
	#nmake /f makefile.vc interface		#这句话暂时不需要
	nmake /f makefile.vc
	nmake /f makefile.vc install

执行完上面两句后，会在csharp文件夹下生成8个dll文件，并将这8个dll文件拷贝到GDAL输出目录下的csharp文件夹中。然后就可以在C#工程中引用这几个dll了，需要注意的是，在使用这几个dll的时候需要将gdal18.dll以及其依赖的其他dll都要拷贝到同一个目录中才能正常运行。

3、编译Java版本GDAL

首先需要JDK环境，没有的可以下载安装一个。然后打开nmake.opt文件，找到大概86行左右的位置：

JAVA_HOME = C:\Program Files\Java\jdk1.6.0_26

将后面的路径修改为JDK的目录后保存。在打开的命令行中使用cd命令定位到swig目录后，输入下面的命令即可：

nmake /f makefile.vc java

4、编译Python版本GDAL

首先在编译Python版本之前，确保自己的电脑中安装了Python，相信大家都装ArcGIS了吧，那么恭喜你，你不用安装Python了，因为在安装ArcGIS的时候必须要安装Python的，同样，将Python的bin目录添加到环境变量Path中去。确保这步完成之后，接下来就是编译Python版本的GDAL。
打开nmake.opt文件，找到大概76行左右的：

PYDIR   =	"C:\Python26"

将后面的路径修改为Python的安装路径后保存。使用cd命令将命令行定位到swig\python目录后，依次输入：

python setup.py build  
python setup.py install  

执行完上述命令后，会在python的site-packages目录看到多了gdal和ogr的文件以及一个osgeo的文件夹。我本机的目录是C:\Python26\Lib\site-packages。然后将编译出来的gdal18.dll以及它依赖的所有的dll都拷贝到site-packages文件夹中的osgeo文件夹中，最后就可以在Python中使用imort gdal来使用GDAL了。测试Python版本的gdal是否安装成功，可以使用下面命令：

from osgeo import gdal
from osgeo.gdalconst import *
dataset=gdal.Open("F:\Work\Data\envi.img",GA_ReadOnly)
dataset.GetDriver().ShortName
#'ENVI' #图像格式
dataset.GetProjectionRef()
#'PROJCS["unnamed",GEOGCS["NAD83",DATUM["North_American_Datum_1983",SPHEROID["GRS 1980",6378137,298.257222101,AUTHORITY["EPSG","7019"]],TOWGS84[0,0,0,0,0,0,0],AUTHORITY["EPSG","6269"]],PRIMEM["Greenwich",0,AUTHORITY["EPSG","8901"]],UNIT["degree",0.0174532925199433,AUTHORITY["EPSG","9108"]],AUTHORITY["EPSG","4269"]],PROJECTION["Transverse_Mercator"],PARAMETER["latitude_of_origin",30],PARAMETER["central_meridian",-84.16666666666667],PARAMETER["scale_factor",0.9999],PARAMETER["false_easting",2296587.926509186],PARAMETER["false_northing",0],UNIT["Foot (International)",0.3048]]' #图像投影信息

注意，上面命令中开头为#号的表示的是Python输出的。如果能输出上面的信息，那么GDAL for Python就安装成功了。

二、开发帮助文档生成

1、Doxygen介绍

以下内容摘自维基百科，地址http://zh.wikipedia.org/wiki/Doxygen。 
Doxygen 是一个 C++, C, Java, Objective-C、Python、IDL (CORBA 和 Microsoft flavors)、Fortran、VHDL、PHP、C#和D语言的文档生成器。可以运行在大多数类Unix系统，以及Mac OS X操作系统和Microsoft Windows 。 初始版本的Doxygen借鉴了一些老版本DOC++的代码；随后，Doxygen源代码由Dimitri van Heesch重写。
Doxygen是一个编写软件参考文档的工具。 该文档是直接写在代码中，因此比较容易保持更新。 Doxygen 可以交叉引用文档和代码，使文件的读者可以很容易地引用实际的代码。
KDE 使用Doxygen作为其部分文档且 KDevelop 具有内置的支持。 Doxygen的发布遵守GNU General Public License，并且是自由软件。
需要注意的是在使用doxygen的时候，会自动生成一些类图，以及函数调用关系图，如果要生成这些图，还需要另外一个很牛叉的开源库Graphviz。Graphviz （Graph Visualization Software的缩写）是一个由AT&T实验室启动的开源工具包，用于绘制DOT语言脚本描述的图形。它也提供了供其它软件使用的库。Graphviz是一个自由软件，其授权为Common Public License。其Mac版本曾经获得2004年的苹果设计奖。更多关于Graphviz的介绍参考其官方网站：http://www.graphviz.org/。

2、生成GDAL开发帮助文档

首先下载安装Doxygen和Graphviz，安装完之后最好将Doxygen和Graphviz的bin目录添加到系统环境变量Path中去。负责要设置一些参数，比较麻烦，还是放到Path中方便。

安装完Doxygen后，会在开始菜单中有个doxywizard.exe的程序，打开，然后在File->Open…菜单中选择GDAL源代码目录下的Doxyfile文件，然后，切换到Run标签，点击Run Doxygen按钮，接下来就会自动提取源代码中的注释生成一份gdal的帮助文档，默认的输出目录是GDAL目录下的html目录。等待生成结束后，点击左下角的Show Html Output后会打开生成的帮助文档。如下图：

 
再次，基本上GDAL的帮助文档生成完成，打开后会发现和GDAL的官方网站一模一样。但是还有个问题，这里只是生成的是GDAL的帮助文档，没有OGR的帮助文档，同样按照上面的步骤，打开GDAL目录下的OGR文件夹下的Doxyfile。然后点击生成，生成的目录默认为ogr文件夹下有个html文件夹，将该文件夹重命名为ogr，然后整个拷贝到上一层的html中，同时将GDAL目录中的doc文件夹中的文件除dox文件以外的文件全部拷贝到html文件夹中。
最后，还记得编译GDAL后生成的html文件夹吗？将这两个文件夹中的内容进行合并，然后你就得到了一份完完整整的GDAL的帮助文档。首页是html文件夹下的index.html。如下图：

 

3、Doxygen脚本配置以及代码注释书写规范

对于Doxygen的脚本配置，可以打开doxywizard后，在Wizard和Expert 标签中在每一项中，鼠标移动到上面，在左下角的试图区域会显示很详细的帮助信息（英文的，不是很难），这里有篇说明文档《 Doxygen配置使用指南》，http://read.pudn.com/downloads151/doc/653112/Doxygen_Using_Manual.pdf。文档中包含了所有的东西，很不错的东西。

第三篇完，下一篇,GDAL工具集简介，敬请期待新作！