NetCDF  4.9.2
building-with-cmake.md
1 Build Instructions for NetCDF-C using CMake {#netCDF-CMake}
2 ===========================================
3 
4 [TOC]
5 
6 # Overview {#cmake_overview}
7 
8 Starting with netCDF-C 4.3.0, we are happy to announce the inclusion of CMake support. CMake will allow for building netCDF on a wider range of platforms, include Microsoft Windows with Visual Studio. CMake support also provides robust unit and regression testing tools. We will also maintain the standard autotools-based build system in parallel.
9 
10 In addition to providing new build options for netCDF-C, we will also provide pre-built binary downloads for the shared versions of netCDF for use with Visual Studio.
11 
12 
13 # Requirements {#cmake_requirements}
14 The following packages are required to build netCDF-C using CMake.
15 
16 * netCDF-C Source Code
17 * CMake version 2.8.12 or greater.
18 * Optional Requirements:
19  * HDF5 Libraries for netCDF4/HDF5 support.
20  * libcurl for DAP support.
21 
22 <center>
23 <img src="deptree.jpg" height="250px" />
24 </center>
25 
26 # The CMake Build Process {#cmake_build}
27 
28 There are four steps in the Build Process when using CMake
29 
30 1. Configuration: Before compiling, the software is configured based on the desired options.
31 2. Building: Once configuration is complete, the libraries are compiled.
32 3. Testing: Post-build, it is possible to run tests to ensure the functionality of the netCDF-C libraries.
33 4. Installation: If all tests pass, the libraries can be installed in the location specified during configuration.
34 
35 For users who prefer pre-built binaries, installation packages are available at \ref winbin
36 
37 ## Configuration {#cmake_configuration}
38 
39 The output of the configuration step is a project file based on the appropriate configurator specified. Common configurators include:
40 
41 * Unix Makefiles
42 * Visual Studio
43 * CodeBlocks
44 * ... and others
45 
46 ### Common CMake Options {#cmake_common_options}
47 
48 | **Option** | **Autotools** | **CMake** |
49 | :------- | :---- | :----- |
50 Specify Install Location | --prefix=PREFIX | -D"CMAKE\_INSTALL\_PREFIX=PREFIX"
51 Enable/Disable netCDF-4 | --enable-netcdf-4<br>--disable-netcdf-4 | -D"ENABLE\_NETCDF\_4=ON" <br> -D"ENABLE\_NETCDF\_4=OFF"
52 Enable/Disable DAP | --enable-dap <br> --disable-dap | -D"ENABLE\_DAP=ON" <br> -D"ENABLE\_DAP=OFF"
53 Enable/Disable Utilities | --enable-utilities <br> --disable-utilities | -D"BUILD\_UTILITIES=ON" <br> -D"BUILD\_UTILITIES=OFF"
54 Specify shared/Static Libraries | --enable-shared <br> --enable-static | -D"BUILD\_SHARED\_LIBS=ON" <br> -D"BUILD\_SHARED\_LIBS=OFF"
55 Enable/Disable Tests | --enable-testsets <br> --disable-testsets | -D"ENABLE\_TESTS=ON" <br> -D"ENABLE\_TESTS=OFF"
56 Specify a custom library location | Use *CFLAGS* and *LDFLAGS* | -D"CMAKE\_PREFIX\_PATH=/usr/custom_libs/"
57 
58 A full list of *basic* options can be found by invoking `cmake [Source Directory] -L`. To enable a list of *basic* and *advanced* options, one would invoke `cmake [Source Directory] -LA`.
59 
60 ### Configuring your build from the command line. {#cmake_command_line}
61 
62 The easiest configuration case would be one in which all of the dependent libraries are installed on the system path (in either Unix/Linux or Windows) and all the default options are desired. From the build directory (often, but not required to be located within the source directory):
63 
64 > $ cmake [Source Directory]
65 
66 If you have libraries installed in a custom directory, you may need to specify the **CMAKE\_PREFIX_PATH** variable to tell cmake where the libraries are installed. For example:
67 
68 > $ cmake [Source Directory] -DCMAKE\_PREFIX\_PATH=/usr/custom_libraries/
69 
70 ## Building {#cmake_building}
71 
72 The compiler can be executed directly with 'make' or the appropriate command for the configurator which was used.
73 
74 > $ make
75 
76 Building can also be executed indirectly via cmake:
77 
78 > $ cmake --build [Build Directory]
79 
80 ## Testing {#cmake_testing}
81 
82 Testing can be executed several different ways:
83 
84 > $ make test
85 
86 or
87 
88 > $ ctest
89 
90 or
91 
92 > $ cmake --build [Build Directory] --target test
93 
94 ## Installation {#cmake_installation}
95 
96 Once netCDF has been built and tested, it may be installed using the following commands:
97 
98 > $ make install
99 
100 or
101 
102 > $ cmake --build [Build Directory] --target install
103 
104 # See Also {#cmake_see_also}
105 
106 For further information regarding NetCDF and CMake, see \ref cmake_faq