Archive:Development/Tutorials/CMake (zh TW)

From KDE TechBase
Revision as of 04:29, 30 November 2009 by Alisha (talk | contribs)


Development/Tutorials/CMake


介紹

CMake 讀取指令檔並且為執行平臺的原生構建系統產生輸入檔。它可以生成 GNU Makefiles、KDevelop 專案檔、XCode 專案檔以及 Visual Studio 專案檔。

CMake 是自由軟體並在 BSD 授權下發佈。它是由Kitware 公司開發。

您可以在TechBase 上的 CMake 頁面找到更多 CMake 相關的資訊。

為什麼使用 CMake？

CMake 是 KDE 4 發行的官方工具，是在2006年3月所決定的。相較過去的 KDE 工具 automake 和 unsermake，技術上的不同點有：

  • CMake 是獨立於 KDE 開發，它也可以被用於其它專案
  • 編譯時間更快，主要是因為沒有使用libtool
  • 建構檔更容易編寫

如何使用 CMake 編譯 KDE

取得和安裝CMake

Linux、BSD 和其他 Unix 系統

從這裡取得最新的 CMake 穩定版。

下載完成後，解壓並編譯： $ mkdir cmake-build $ cd cmake-build $ ../bootstrap $ make $ make install

預設情況下，會安裝 CMake 在 /usr/local。所以請確定 /usr/local/bin 在您的執行路徑（execute path）中。想要改變安裝路徑（例如 debian 中改為 /usr），請在 bootstrap 指令中加入 '--prefix=PATH' 選項。

如果你想使用目前的開發版本，請依循這裡的說明。

Windows

從這裡取得最新的 CMake 穩定版。

下載完成後，執行 cmake 安裝程式。

預設將安裝 CMake 在 C:\Program Files\CMake 2.8。所以請確定 <installpath>\bin 在你的執行路徑中。

如果你想使用目前的開發版本，請依循這裡的說明。

執行 CMake

Linux、BSD 和其他 Unix 系統

你必須執行 CMake 來為你的系統生成建構檔。CMake支援 in-source 和 out-of-source 建構，不過目前 KDE 預設禁用 in-source 建構。

假設你在 ~/src/kdelibs/ 中有 kdelibs/，那麼，輸入： $ ls kdelibs/ $ mkdir kdelibs-build $ cd kdelibs-build $ cmake ../kdelibs 這會在 kdelibs-build/中生成建構 kdelibs/ 的 Makefiles。

Windows

你必須執行 CMake 來為你的系統生成建構檔。CMake支援 in-source 和 out-of-source 建構，不過目前 KDE 預設禁用 in-source 建構。

假設你在 c:\daten\kde4 中有 kdelibs\，那麼，輸入： c:\daten\kde4> cd kdelibs\win c:\daten\kde4> cmake c:\daten\kde4> make c:\daten\kde4> make install c:\daten\kde4> cd .. c:\daten\kde4> mkdir kdelibs-build c:\daten\kde4> cd kdelibs-build c:\daten\kde4\kdelibs-build> cmake ..\kdelibs

這樣就在 kdelibs-build\中生成建構 kdelibs\ 的 Makefiles。想了解更多關於在 Windows 編譯KDE 的資訊，請閱讀KDE on Windows。

KDevelop 3 專案檔

If you prefer project files for KDevelop 3 (which will basically be Makefiles accompanied by some extra files for KDevelop), run it like this: $ cmake ../kdelibs -GKDevelop3 Use 'cmake -h' to find out which generators CMake supports and the other options.

CMake 和 Qt4

為了定位 Qt 4，CMake 會在你的執行路徑中搜尋 qmake。CMake 不會使用 QTDIR 環境變數。所以請確定在執行路徑中找到的第一個 qmake 就是你希望使用的。

更多細節

當 CMake 執行完成後，它會生成一個｢CMakeCache.txt｣檔案。這個檔案包含了所有 CMake 在你的系統上偵測到的設定。如果你希望在其他生成器（generators)上執行 CMake，或你希望 CMake 重新偵測系統，請刪除這個檔案。

如果有些東西你知道它在哪，但 CMake 沒有偵測到，你可以手動的告訴 CMake 到哪裡去找它。CMake 使用變數儲存這些資訊。這些變數快取在前面提到的 CMakeCache.txt中。有3個選項可以手工調整這些變數：

  • tell CMake the correct value via the command line: cmake ../kdelibs -DNAME_OF_THE_VARIABLE=value
  • use ccmake, which provides a curses based GUI to adjust the CMake variables (run: ccmake ../kdelibs)
  • edit the file CMakeCache.txt directly (not recommended)

You should run "ccmake ../kdelibs" at least once so that you get an impression which variables CMake uses. Press "T" to see also the "advanced" variables. So, if CMake didn't find something, start ccmake and adjust it manually.

Command Line Variables

Some cmake command line variables you may want to set:

  • CMAKE_INSTALL_PREFIX: cmake ../kdelibs -DCMAKE_INSTALL_PREFIX=/opt/kde4 is the equivalent to ./configure --prefix=/opt/kde4
  • CMAKE_BUILD_TYPE: decide which type of build you want. You can choose between "debugfull", "Debug", "Profile", "RelWithDebInfo" and "Release". The default is "RelWithDebInfo". Please refer to page CMake Build Types for a more detailed explanation.
  • KDE4_BUILD_TESTS=ON: creates Makefiles with build test programs and also provides 'test' targets
  • KDE4_TEST_OUTPUT=xml: Unit tests using the QTestLib framework will create xml formatted logfiles.
  • KDE4_DISABLE_MULTIMEDIA=ON: Build KDE without any multimedia (audio and video) support.
  • BUILD_foo=OFF: disables the build for the project in subdirectory 'foo'.
  • WITH_foo: there are several options, e.g. WITH_CUPS or WITH_Jasper. If you disable them, cmake will not even try to find this package. If it is enabled, cmake will try to find it. If it fails with this, you can still adjust it manually as described above.

環境變數

If you have headers and libraries installed in non-standard locations that cmake cannot find (e.g., fink on Mac OSX installs to /sw), then set the following as environment variables. This can be also very useful e.g. if you install kdesupport to ~/install/kdesupport . Despite the similar naming convention, these will not work as arguments on the cmake command line:

  • CMAKE_INCLUDE_PATH, eg. export CMAKE_INCLUDE_PATH=/sw/include
  • CMAKE_LIBRARY_PATH, eg. export CMAKE_LIBRARY_PATH=/sw/lib
  • CMAKE_PROGRAM_PATH, eg. export CMAKE_LIBRARY_PATH=/sw/bin

With CMake 2.6.0 and above the same effect can be achieved by setting just one variable:

  • CMAKE_PREFIX_PATH, eg. export CMAKE_PREFIX_PATH=/sw


For more information on variables, see this cmake.org wiki page

更進一步

If cmake finishes with "Generating done" then there was no errors, but if it finishes with "Configuring done" then there was errors that you have to fix. Once cmake finishes successfully, run your buildtool (i.e. make, KDevelop, XCode or MSVC) and build and wait until it has finished. Then "make install".

If you got a failure that says something like CMake Error: This project requires some variables to be set, and cmake can not find them. Please set the following variables: X11_XTest_LIB (ADVANCED) then you may have a missing library (or other dependency). To find out which library, search in the cmake/modules directory for the variable that cmake can't find. In the example above, it is find_library(X11_XTest_LIB Xtst ${X11_LIB_SEARCH_PATH}) So the missing library is Xtst. You then need to find it (perhaps installing a libXtst-devel library) and re-run cmake.

使用CMake在簡單的應用程式中

Here's the most simple CMakeLists.txt: add_executable(hello main.cpp) This will create an executable named "hello" (or "hello.exe" under Windows) from the source file main.cpp. You can mix C and C++ files as you want. You can have multiple executables and libraries in one CMakeLists.txt. The same source file can be used in multiple targets, it will be compiled for each target independently from the other targets. Probably the most important part of the cmake language are the variables: set( MY_SOURCES main.cpp widget.cpp) message(STATUS "my sources: ${MY_SOURCES}") So, use the SET() command to set the value of a variable. If you list more than one string, the variable will be a list. A list is a list of strings separated by semicolons. If you set it to only one item, it will have just that value. To get the value of a variable, use ${VAR}. You can iterate over a list using FOREACH(): foreach(next_ITEM ${MY_SOURCES}) 

  message(STATUS "next item: ${next_ITEM}")

endforeach(next_ITEM ${MY_SOURCES}) The commands in CMake are case-insensitive. Names of variables and names of parameter are case-sensitive.

You can also test for various things: if (UNIX) 

  message(STATUS "This is UNIX (including OS X and CygWin)")

endif (UNIX)

if (MSVC) 

  set(MY_SRCS ${MY_SRCS} winextra.cpp)

endif (MSVC) In this second example you can see also how to append items to a list.

In the cmake Wiki there is also a tutorial on using cmake to build KDE 4 software. It is recommended reading.

使用 CMake 在 KDE 專案中

Here's a basic CMakeList file that builds a small KDE 4 project: project( kde4project ) find_package( KDE4 REQUIRED ) include_directories( ${KDE4_INCLUDES} )

set( KDE4ProjectSources kde4mainapp.cpp someclass.cpp someotherclass.cpp )

kde4_add_executable( kde4project ${KDE4ProjectSources} )

target_link_libraries( kde4project ${KDE4_KDEUI_LIBS} ${KDE4_KPARTS_LIBS} )

install( TARGETS kde4project ${INSTALL_TARGETS_DEFAULT_ARGS} )

target_link_libraries contains the development libraries that are linked to your program. E.g. if you want to link to libtidy-devel, your library file name may be called /usr/local/lib/libtidy.a. You would then add -ltidy to a gcc call. Here, you add tidy to your target_link_libraries. If possible, use pre-defined variables or macros like ${KDE4_KDEUI_LIBS}.

install (TARGETS is where the target will finally be installed. If you do not have this line, make install will not be available.

Variables, macros and other useful information specific to KDE can be found at the CMake addons for KDE page.

擴展 CMake

CMake can be extended using cmake scripts. CMake comes with a number of scripts; under UNIX they are by default installed to /usr/local/share/CMake/Modules/. The KDE libraries install also a set of cmake modules into share/apps/cmake/modules/. The files located there will be preferred over the ones in the system global cmake module path. For detecting software packages there are FindFOO.cmake files, see here for more information. You can also write macros in CMake. They are powerful enough to do most things you will need to build software, but they are not intended to be used as a general purpose programming language.

轉換基於 autotools 的 KDE 軟體使用 CMake

In kdesdk/cmake/ you can find a script am2cmake . This is a ruby script, so you need to have ruby installed. Run am2cmake in the toplevel directory of your sources: $ cd src/mykooltool/ $ am2cmake --kde4 Don't forget the switch "--kde4", otherwise it won't generate files suitable for KDE 4 software. The converted files 'may' work as they are, but complicated projects will require some additional editing.

You may have to:

  • add more include direcories, using INCLUDE_DIRECTORIES()
  • add more link libraries, using TARGET_LINK_LIBRARIES()
  • add some compile switches, using ADD_DEFINITIONS()
  • add some "configure" checks, see How To Do Platform Checks and How To Find Installed Software
  • take special care of former libtool convenience libraries. They are not supported by cmake, instead there will be a file ConvenienceLibs.cmake created. In this file you will find for every convenience lib a variable, which contains all source files of this convenience lib. For the targets which linked to this convenience lib, just add the variable to the sources.
  • a file AdditionalInfo.txt will be created. There you will see all *.in and *.in.in files of your project. The stuff done in these files will have to be converted manually to cmake.
Retrieved from "https://techbase.kde.org/index.php?title=Archive:Development/Tutorials/CMake_(zh_TW)&oldid=47039"