1 前言
1.1 引言
SWIG (Simplified Wrapper and Interface Generator) is a software development tool for building scripting language interfaces to C and C++ programs. Originally developed in 1995, SWIG was first used by scientists in the Theoretical Physics Division at Los Alamos National Laboratory for building user interfaces to simulation codes running on the Connection Machine 5 supercomputer. In this environment, scientists needed to work with huge amounts of simulation data, complex hardware, and a constantly changing code base. The use of a scripting language interface provided a simple yet highly flexible foundation for solving these types of problems. SWIG simplifies development by largely automating the task of scripting language integration--allowing developers and users to focus on more important problems.
Although SWIG was originally developed for scientific applications, it has since evolved into a general purpose tool that is used in a wide variety of applications--in fact almost anything where C/C++ programming is involved.
SWIG（Simplified Wrapper and Interface Generator）是一個用於構建 C 和 C++ 程序腳本語言接口的軟件開發工具。SWIG 開發於 1995 年，最初由洛斯·阿拉莫斯國家實驗室理論物理部門的科學家使用，用於構建運行在 Connection Machine 5 超級計算機上的模擬代碼的用戶接口。在這種環境中，科學家們需要處理大量的模擬數據、復雜的硬件和不斷變化的代碼庫。腳本語言接口的使用為解決這些類型的問題提供了簡單而高度靈活的基礎。SWIG 通過大大自動化腳本語言集成任務簡化了開發，這允許開發人員和用戶專注於更重要的問題。
盡管 SWIG 最初是為科學應用程序而開發的，但它已經發展成為一種通用工具，可用於各種應用程序，實際上凡是涉及 C/C++ 編程的都可以。
1.2 SWIG 版本
In the late 1990's, the most stable version of SWIG was release 1.1p5. Versions 1.3.x were officially development versions and these were released over a period of 10 years starting from the year 2000. The final version in the 1.3.x series was 1.3.40, but in truth the 1.3.x series had been stable for many years. An official stable version was released along with the decision to make SWIG license changes and this gave rise to version 2.0.0 in 2010.
在 1990 年代后期，最穩定的 SWIG 版本是 1.1p5 版本。版本 1.3.x 是正式開發版本，從 2000 年開始這些版本陸續在 10 年內發布。1.3.x 系列的最終版本是 1.3.40，但事實上 1.3.x 系列已經穩定了很多年。隨着修改 SWIG 許可證的決定發布了官方穩定版本，這導致了 2010 年的版本 2.0.0。
1.3 SWIG 許可證
The LICENSE file shipped with SWIG in the top level directory contains the SWIG license. For further insight into the license including the license of SWIG's output code, please visit the SWIG legal page - http://www.swig.org/legal.html.
The license was clarified in version 2.0.0 so that the code that SWIG generated could be distributed under license terms of the user's choice/requirements and at the same time the SWIG source was placed under the GNU General Public License version 3.
SWIG 在頂層目錄中附帶的 LICENSE 文件包含 SWIG 許可證。如需進一步了解許可證，包括 SWIG 輸出代碼的許可證，請訪問 SWIG 的法律頁面——http://www.swig.org/legal.html。
許可證在 2.0.0 版本中得到了澄清，因此 SWIG 生成的代碼可以根據用戶選擇和要求的許可條款進行發布，同時 SWIG 源代碼遵循 GPL 3 許可證。
1.4 SWIG 資源
The official location of SWIG related material is
SWIG 相關資料的官方網址是
http://www.swig.org
This site contains the latest version of the software, users guide, and information regarding bugs, installation problems, and implementation tricks.
You can also subscribe to the swig-user mailing list by visiting the page
該站點包含最新版本的軟件、用戶指南以及有關錯誤、安裝問題和實現技巧的信息。
你還可以通過訪問該頁面訂閱 swig-user 郵件列表
http://www.swig.org/mail.html
The mailing list often discusses some of the more technical aspects of SWIG along with information about beta releases and future work.
Git and Subversion access to the latest version of SWIG is also available. More information about this can be obtained at:
郵件列表更多討論一些 SWIG 的技術內容，以及有關 beta 版本和未來工作的信息。
也可以通過 Git 和 Subversion 獲得最新版本的 SWIG。有關這方面的更多信息，請訪問：
SWIG Bleeding Edge
1.5 前提要求
This manual assumes that you know how to write C/C++ programs and that you have at least heard of scripting languages such as Tcl, Python, and Perl. A detailed knowledge of these scripting languages is not required although some familiarity won't hurt. No prior experience with building C extensions to these languages is required---after all, this is what SWIG does automatically. However, you should be reasonably familiar with the use of compilers, linkers, and makefiles since making scripting language extensions is somewhat more complicated than writing a normal C program.
Over time SWIG releases have become significantly more capable in their C++ handling--especially support for advanced features like namespaces, overloaded operators, and templates. Whenever possible, this manual tries to cover the technicalities of this interface. However, this isn't meant to be a tutorial on C++ programming. For many of the gory details, you will almost certainly want to consult a good C++ reference. If you don't program in C++, you may just want to skip those parts of the manual.
本手冊假定你知道如何編寫 C/C++ 程序，並且至少聽說過 Tcl、Python 和 Perl 等腳本語言。不要求詳細了解這些腳本語言，但熟悉總沒壞處。不要求有為這些語言構建 C 擴展的經驗——畢竟，這是 SWIG 自動執行的操作。但是，你應該相當熟悉編譯器、鏈接器和 makefile 的使用，因為編寫腳本語言擴展比編寫普通的 C 程序要復雜一些。
隨着時間的推移，SWIG 在處理 C++ 方面的能力顯着提高——尤其是對命名空間、重載運算符和模板等高級功能的支持。只要有可能，本手冊將嘗試涵蓋此接口的技術細節。但是，這並不是一本關於 C++ 編程的教程。對於許多深層的細節，你幾乎肯定想要一本很好的 C++ 參考手冊。如果你不使用 C++ 編程，你可能想直接跳過本手冊的這些部分。
1.6 本手冊的組織構成
The first few chapters of this manual describe SWIG in general and provide an overview of its capabilities. The remaining chapters are devoted to specific SWIG language modules and are self contained. Thus, if you are using SWIG to build Python interfaces, you can probably skip to that chapter and find almost everything you need to know.
本手冊的前幾章概述了 SWIG，提供了其功能的概覽。其余章節專門介紹特定的 SWIG 語言模塊，並且它們是自給自足的。因此，如果你使用 SWIG 構建 Python 接口，你可以跳到該章並能找到你需要知道的幾乎所有內容。
1.7 如何避免閱讀手冊
If you hate reading manuals, glance at the "Introduction" which contains a few simple examples. These examples contain about 95% of everything you need to know to use SWIG. After that, simply use the language-specific chapters as a reference. The SWIG distribution also comes with a large directory of examples that illustrate different topics.
如果你討厭閱讀手冊，請瀏覽一下“引言”，其中包含一些簡單的例子。這些示例包含使用 SWIG 所有需要了解內容的 95%。之后，只需使用特定語言的章節作為參考。SWIG 發行版還附帶了一個涵蓋不同主題的大型示例目錄。
1.8 向后兼容
If you are a previous user of SWIG, don't expect SWIG to provide complete backwards compatibility. Although the developers strive to the utmost to keep backwards compatibility, this isn't always possible as the primary goal over time is to make SWIG better---a process that would simply be impossible if the developers are constantly bogged down with backwards compatibility issues. Potential incompatibilities are clearly marked in the detailed release notes.
If you need to work with different versions of SWIG and backwards compatibility is an issue, you can use the SWIG_VERSION preprocessor symbol which holds the version of SWIG being executed. SWIG_VERSION is a hexadecimal integer such as 0x010311 (corresponding to SWIG-1.3.11). This can be used in an interface file to define different typemaps, take advantage of different features etc:
如果你是 SWIG 的老用戶，請不要期望 SWIG 提供完全的向后兼容性。盡管開發人員力求最大程度地保持向后兼容性，但隨着時間的推移，這並不總是可行的，因為開發人員的主要目標是使 SWIG 更好用，如果開發人員不斷陷入向后兼容性問題，這個任務根本不可能實現。潛在的不兼容性在 release notes 中有詳細的明確標記。
如果你需要使用不同版本的 SWIG，並且向后兼容性是一個問題，你可以使用
SWIG_VERSION預處理符來固定正在運行的 SWIG 版本。SWIG_VERSION是十六進制整數，例如0x010311（對應於 SWIG-1.3.11）。這可以在接口文件中用於定義不同的類型映射，利用不同的功能等：
#if SWIG_VERSION >= 0x010311
/* Use some fancy new feature */
#endif
Note: The version symbol is not defined in the generated SWIG wrapper file. The SWIG preprocessor has defined SWIG_VERSION since SWIG-1.3.11.
注意：版本符號未在生成的 SWIG 包裝器文件中定義。自 SWIG-1.3.11 起，SWIG 才定義了預處理符
SWIG_VERSION。
1.9 發行說明
The CHANGES.current, CHANGES and RELEASENOTES files shipped with SWIG in the top level directory contain, respectively, detailed release notes for the current version, detailed release notes for previous releases and summary release notes from SWIG-1.3.22 onwards.
SWIG 在頂層目錄中附帶的 CHANGES.current、CHANGES 和 RELEASENOTES 文件分別包含當前版本的詳細發行說明，以前版本的詳細發行說明，以及 SWIG-1.3.22 以后的發行說明摘要。
1.10 捐贈
SWIG is an unfunded project that would not be possible without the contributions of many people working in their spare time. If you have benefitted from using SWIG, please consider Donating to SWIG to keep development going. There have been a large varied number of people who have made contributions at all levels over time. Contributors are mentioned either in the COPYRIGHT file or CHANGES files shipped with SWIG or in submitted bugs.
SWIG 是一個沒有資金支持的項目，沒有許多人在業余時間工作的貢獻，該項目是不可能的。如果你從使用 SWIG 中受益，請考慮捐贈給 SWIG 以支持開發。歷史上，大量的人員在各種層面上做出貢獻。COPYRIGHT 文件中提及了貢獻者，SWIG 附帶的 CHANGES 文件或提交的錯誤中也有提及。
1.11 錯誤報告
Although every attempt has been made to make SWIG bug-free, we are also trying to make feature improvements that may introduce bugs. To report a bug, either send mail to the SWIG developer list at the swig-devel mailing list or report a bug at the SWIG bug tracker. In your report, be as specific as possible, including (if applicable), error messages, tracebacks (if a core dump occurred), corresponding portions of the SWIG interface file used, and any important pieces of the SWIG generated wrapper code. We can only fix bugs if we know about them.
盡管已經盡一切努力使 SWIG 無錯誤，但我們也試圖進行功能改進，這可能會引入錯誤。要報告錯誤，請將郵件發送到 swig-devel 郵件列表上的 SWIG 開發人員列表，或報告 SWIG 錯誤跟蹤器中的錯誤。你的報告應該盡可能具體，引用（如果適用的話）、錯誤消息、回溯（如果發生內核問題）、使用的 SWIG 接口文件的相應部分，以及 SWIG 生成的包裝器代碼的任何重要部分。有了解它們，我們才能修復錯誤。
1.12 安裝
1.12.1 Windows 安裝
Please see the dedicated Windows chapter for instructions on installing SWIG on Windows and running the examples. The Windows distribution is called swigwin and includes a prebuilt SWIG executable, swig.exe, included in the top level directory. Otherwise it is exactly the same as the main SWIG distribution. There is no need to download anything else.
有關在 Windows 上安裝 SWIG 並運行示例的說明，請參閱專用的 Windows 章節。Windows 發行版稱為 swigwin，包含一個在頂層目錄中的預構建 SWIG 可執行文件 swig.exe。它與 SWIG 主分布版本完全相同。無需下載任何其他內容。
1.12.2 Unix 安裝
These installation instructions are for using the distributed tarball, for example, swig-3.0.8.tar.gz. If you wish to build and install from source on Github, extra steps are required. Please see the Bleeding Edge page on the SWIG website.
You must use GNU make to build and install SWIG.
PCRE needs to be installed on your system to build SWIG, in particular pcre-config must be available. If you have PCRE headers and libraries but not pcre-config itself or, alternatively, wish to override the compiler or linker flags returned by pcre-config, you may set PCRE_LIBS and PCRE_CFLAGS variables to be used instead. And if you don't have PCRE at all, the configure script will provide instructions for obtaining it.
To build and install SWIG, simply type the following:
這些安裝說明適用於使用發布的壓縮文件，例如
swig-3.0.8.tar.gz。如果你希望通過 Github 從源代碼構建和安裝，則需要執行額外的步驟。請參閱 SWIG 網站上的 Bleeding Edge 頁面。你必須使用 GNU make 來構建和安裝 SWIG。
你的系統需要安裝 PCRE 來構建 SWIG，特別是 pcre-config 必須可用。如果你有 PCRE 頭文件和庫，而不是 pcre-config 本身，或者希望覆蓋 pcre-config 返回的編譯器或鏈接器標志，則可以設置 PCRE_LIBS 和PCRE_CFLAGS 變量來代替使用。如果你根本沒有 PCRE，配置腳本將提供獲取它的說明。
要構建和安裝 SWIG，只需鍵入以下內容：
$ ./configure
$ make
$ make install
By default SWIG installs itself in /usr/local. If you need to install SWIG in a different location or in your home directory, use the --prefix option to ./configure. For example:
默認情況下，SWIG 會自行安裝在
/usr/local中。如果需要在不同的位置或主目錄中安裝 SWIG，請使用./configure的--prefix選項 。例如：
$ ./configure --prefix=/home/yourname/projects
$ make
$ make install
Note: the directory given to --prefix must be an absolute pathname. Do not use the ~ shell-escape to refer to your home directory. SWIG won't work properly if you do this.
The INSTALL file shipped in the top level directory details more about using configure. Also try
注意：給
--prefix的目錄必須是絕對路徑名。不要使用~來引用你的主目錄。如果你這樣做，SWIG 將無法正常工作。頂層目錄中提供的 INSTALL 文件詳細介紹了使用 configure 的更多信息。也可以試試
$ ./configure --help.
The configure script will attempt to locate various packages on your machine including Tcl, Perl5, Python and all the other target languages that SWIG supports. Don't panic if you get 'not found' messages -- SWIG does not need these packages to compile or run. The configure script is actually looking for these packages so that you can try out the SWIG examples contained in the 'Examples' directory without having to hack Makefiles. Note that the --without-xxx options, where xxx is a target language, have minimal effect. All they do is reduce the amount of testing done with 'make check'. The SWIG executable and library files installed cannot currently be configured with a subset of target languages.
SWIG used to include a set of runtime libraries for some languages for working with multiple modules. These are no longer built during the installation stage. However, users can build them just like any wrapper module as described in the Modules chapter. The CHANGES file shipped with SWIG in the top level directory also lists some examples which build the runtime library.
Note:
- If you checked the code out via Git, you will have to run
./autogen.shbefore./configure. In addition, a full build of SWIG requires a number of packages to be installed. Full instructions at SWIG bleeding edge.
configure 腳本將嘗試在你的機器上找到各種軟件包，包括 Tcl、Perl5、Python 和 SWIG 支持的所有其他目標語言。如果你收到“not found”消息，請不要驚慌——SWIG 不需要這些包來編譯或運行。配置腳本實際上正在尋找這些包，以便你可以嘗試“Examples”目錄中包含的 SWIG 示例，而無需破解 Makefile。請注意
--with-xxx選項，其中xxx是目標語言，具有微小的影響。它們所做的就是減少“make check”所做的測試。目前，安裝的 SWIG 可執行文件和庫文件無法配置目標語言的子集。SWIG 過去包含一組用於某些語言的運行時庫，用於處理多個模塊。這些不再在安裝階段構建。但是，用戶可以像模塊章節中所述的任何包裝器模塊一樣構建它們。SWIG 在頂層目錄中附帶的 CHANGES 文件還列出了構建運行時庫的一些示例。
注意：
- 如果你通過 Git 檢查了代碼，則必須在
./configure之前運行./autogen.sh。此外，SWIG 的完整版本需要安裝許多軟件包。完整說明在 SWIG Bleeding Edge中。
1.12.3 Macintosh OS X 安裝
SWIG is known to work on various flavors of OS X. Follow the Unix installation instructions above. However, as of this writing, there is still great deal of inconsistency with how shared libaries are handled by various scripting languages on OS X.
Users of OS X should be aware that Darwin handles shared libraries and linking in a radically different way than most Unix systems. In order to test SWIG and run the examples, SWIG configures itself to use flat namespaces and to allow undefined symbols (-flat_namespace -undefined suppress). This mostly closely follows the Unix model and makes it more likely that the SWIG examples will work with whatever installation of software you might have. However, this is generally not the recommended technique for building larger extension modules. Instead, you should utilize Darwin's two-level namespaces. Some details about this can be found here Understanding Two-Level Namespaces.
Needless to say, you might have to experiment a bit to get things working at first.
眾所周知，SWIG 可以在各種 OS X 上工作。遵循上面的 Unix 安裝說明。但是，在撰寫本文時，OS X 上的各種腳本語言在如何處理動態庫的問題上仍然存在很大的不一致。
OS X 的用戶應該意識到 Darwin 處理動態庫和鏈接的方式與大多數 Unix 系統完全不同。為了測試 SWIG 並運行示例，SWIG 將自己配置為使用平面名稱空間（flat namespaces）並允許未定義的符號（
-flat_namespace -undefined suppress）。這主要是遵循 Unix 模型，並且使 SWIG 示例更可能適用於你可能擁有的任何安裝軟件。但是，這通常不是構建更大擴展模塊的推薦技術。相反，你應該使用 Darwin 的兩級命名空間。有關此內容的一些詳細信息，請參閱理解兩級命名空間。毋庸置疑，你可能需要先嘗試一下才能運轉起來。
1.12.4 測試
If you want to test SWIG after building it, a check can be performed on Unix operating systems. Type the following:
如果要在構建 SWIG 之后測試，可以在 Unix 操作系統上執行檢查。輸入以下內容：
$ make -k check
This step can be performed either before or after installation. The check requires at least one of the target languages to be installed. If it fails, it may mean that you have an uninstalled language module or that the file 'Examples/Makefile' has been incorrectly configured. It may also fail due to compiler issues such as a broken C++ compiler. Even if the check fails, there is a pretty good chance SWIG still works correctly --- you will just have to mess around with one of the examples and some makefiles to get it to work. Some tests may also fail due to missing dependency packages, eg PCRE or Boost, but this will require careful analysis of the configure output done during configuration.
The test suite executed by the check is designed to stress-test many parts of the implementation including obscure corner cases. If some of these tests fail or generate warning messages, there is no reason for alarm --- the test may be related to some new SWIG feature or a difficult bug that we're trying to resolve. Chances are that SWIG will work just fine for you. Note that if you have more than one CPU/core, then you can use parallel make to speed up the check as it does take quite some time to run, for example:
此步驟可在安裝之前或之后執行。該檢查至少需要安裝一種目標語言。如果失敗，則可能意味着你已卸載語言模塊或文件
Examples/Makefile配置錯誤。它也可能由於編譯器問題（例如損壞的 C++ 編譯器）而失敗。即使檢查失敗，SWIG 仍然可以正常工作——你只需要使用其中一個示例和一些 makefile 來使它工作。由於缺少依賴包（例如 PCRE 或 Boost），某些測試也可能會失敗，但這需要仔細分析配置期間完成的配置輸出。檢查執行的測試套件旨在對實現的許多部分進行壓力測試，包括特殊情況。如果其中一些測試失敗或生成警告消息，沒有理由慌張——測試可能與某些新的 SWIG 功能，或我們試圖解決的難題有關。SWIG 依然可能很好地運行。請注意，如果你有多個 CPU 核心，那么你可以使用並行構建來加速檢查，因為它需要相當長的時間來運行，例如：
$ make -j2 -k check
Also, SWIG's support for C++ is sufficiently advanced that certain tests may fail on older C++ compilers (for instance if your compiler does not support member templates). These errors are harmless if you don't intend to use these features in your own programs.
Note: The test-suite currently contains over 500 tests. If you have many different target languages installed and a slow machine, it might take more than an hour to run the test-suite.
此外，SWIG 對 C++ 的支持非常先進，以至於某些測試可能會在較舊的 C++ 編譯器上失敗（例如，如果你的編譯器不支持成員模板的話）。如果你不打算在自己的程序中使用這些功能，則這些錯誤是無害的。
注意：測試套件目前包含 500 多個測試。如果安裝了許多不同的目標語言並且計算機速度較慢，則運行測試套件可能需要一個多小時。
1.12.5 示例
The Examples directory contains a variety of examples of using SWIG and it has some browsable documentation. Simply point your browser to the file "Example/index.html".
The Examples directory also includes Visual C++ project 6 (.dsp) files for building some of the examples on Windows. Later versions of Visual Studio will convert these old style project files into a current solution file.
Examples目錄包含使用 SWIG 的各種示例，它有一些可瀏覽的文檔。只需將瀏覽器指向Example/index.html文件即可。
Examples目錄還包括用於在 Windows 上構建示例的一些 Visual C++ 6 項目文件（.dsp）。更高版本的 Visual Studio 會將這些舊樣式項目文件轉換為當前解決方案文件。