Updated the website built from mesos SHA: 8c0b351.
Project: http://git-wip-us.apache.org/repos/asf/mesos-site/repo Commit: http://git-wip-us.apache.org/repos/asf/mesos-site/commit/a5fb0e1c Tree: http://git-wip-us.apache.org/repos/asf/mesos-site/tree/a5fb0e1c Diff: http://git-wip-us.apache.org/repos/asf/mesos-site/diff/a5fb0e1c Branch: refs/heads/asf-site Commit: a5fb0e1ccaf30de3c7a232215739d55a4ccd96d0 Parents: 8865002 Author: jenkins <bui...@apache.org> Authored: Wed Oct 11 19:48:32 2017 +0000 Committer: jenkins <bui...@apache.org> Committed: Wed Oct 11 19:48:32 2017 +0000 ---------------------------------------------------------------------- content/documentation/agent-recovery/index.html | 2 +- content/documentation/authorization/index.html | 2 +- content/documentation/cmake-examples/index.html | 531 ++++ content/documentation/cmake/index.html | 514 +++ .../configuration-cmake/index.html | 259 -- content/documentation/configuration/index.html | 2958 +----------------- .../documentation/container-image/index.html | 2 +- .../docker-containerizer/index.html | 2 +- content/documentation/fetcher/index.html | 2 +- content/documentation/index.html | 3 +- .../latest/agent-recovery/index.html | 2 +- .../latest/authorization/index.html | 2 +- .../latest/cmake-examples/index.html | 531 ++++ content/documentation/latest/cmake/index.html | 514 +++ .../latest/configuration-cmake/index.html | 259 -- .../latest/configuration/agent/index.html | 1479 +++++++++ .../latest/configuration/autotools/index.html | 729 +++++ .../latest/configuration/cmake/index.html | 312 ++ .../latest/configuration/index.html | 2958 +----------------- .../latest/configuration/libprocess/index.html | 261 ++ .../configuration/master-and-agent/index.html | 535 ++++ .../latest/configuration/master/index.html | 731 +++++ .../latest/container-image/index.html | 2 +- .../latest/docker-containerizer/index.html | 2 +- content/documentation/latest/fetcher/index.html | 2 +- content/documentation/latest/index.html | 3 +- content/documentation/latest/logging/index.html | 3 +- content/documentation/latest/sandbox/index.html | 2 +- content/documentation/logging/index.html | 3 +- content/documentation/sandbox/index.html | 2 +- content/sitemap.xml | 48 +- 31 files changed, 6231 insertions(+), 6424 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/mesos-site/blob/a5fb0e1c/content/documentation/agent-recovery/index.html ---------------------------------------------------------------------- diff --git a/content/documentation/agent-recovery/index.html b/content/documentation/agent-recovery/index.html index c8cb08a..9864bc0 100644 --- a/content/documentation/agent-recovery/index.html +++ b/content/documentation/agent-recovery/index.html @@ -154,7 +154,7 @@ In other cases such as checkpointed resources (e.g. persistent volumes) being in <h2>Agent Configuration</h2> -<p>Three <a href="/documentation/latest/./configuration/">configuration flags</a> control the recovery behavior of a Mesos agent:</p> +<p>Three <a href="/documentation/latest/./configuration/agent/">configuration flags</a> control the recovery behavior of a Mesos agent:</p> <ul> <li><p><code>strict</code>: Whether to do agent recovery in strict mode [Default: true].</p> http://git-wip-us.apache.org/repos/asf/mesos-site/blob/a5fb0e1c/content/documentation/authorization/index.html ---------------------------------------------------------------------- diff --git a/content/documentation/authorization/index.html b/content/documentation/authorization/index.html index bfad49c..518284a 100644 --- a/content/documentation/authorization/index.html +++ b/content/documentation/authorization/index.html @@ -125,7 +125,7 @@ frameworks subscribed to any roles.</p> use cases. This authorizer is configured using Access Control Lists (ACLs). Alternative implementations could express their authorization rules in different ways. The local authorizer is used if the -<a href="/documentation/latest/./configuration/"><code>--authorizers</code></a> flag is not specified (or manually set to +<a href="/documentation/latest/./configuration/master/"><code>--authorizers</code></a> flag is not specified (or manually set to the default value <code>local</code>) and ACLs are specified via the <a href="/documentation/latest/./configuration/"><code>--acls</code></a> flag.</p> http://git-wip-us.apache.org/repos/asf/mesos-site/blob/a5fb0e1c/content/documentation/cmake-examples/index.html ---------------------------------------------------------------------- diff --git a/content/documentation/cmake-examples/index.html b/content/documentation/cmake-examples/index.html new file mode 100644 index 0000000..c6df745 --- /dev/null +++ b/content/documentation/cmake-examples/index.html @@ -0,0 +1,531 @@ +<!DOCTYPE html> +<html> + <head> + <meta charset="utf-8"> + <title>Apache Mesos - CMake By Example</title> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + + <meta property="og:locale" content="en_US"/> + <meta property="og:type" content="website"/> + <meta property="og:title" content="Apache Mesos"/> + <meta property="og:site_name" content="Apache Mesos"/> + <meta property="og:url" content="http://mesos.apache.org/"/> + <meta property="og:image" content="http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/> + <meta property="og:description" + content="Apache Mesos abstracts resources away from machines, + enabling fault-tolerant and elastic distributed systems + to easily be built and run effectively."/> + + <meta name="twitter:card" content="summary"/> + <meta name="twitter:site" content="@ApacheMesos"/> + <meta name="twitter:title" content="Apache Mesos"/> + <meta name="twitter:image" content="http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/> + <meta name="twitter:description" + content="Apache Mesos abstracts resources away from machines, + enabling fault-tolerant and elastic distributed systems + to easily be built and run effectively."/> + + <link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet"> + <link rel="alternate" type="application/atom+xml" title="Apache Mesos Blog" href="/blog/feed.xml"> + <link href="../../assets/css/main.css" media="screen" rel="stylesheet" type="text/css" /> + + + + <!-- Google Analytics Magic --> + <script type="text/javascript"> + var _gaq = _gaq || []; + _gaq.push(['_setAccount', 'UA-20226872-1']); + _gaq.push(['_setDomainName', 'apache.org']); + _gaq.push(['_trackPageview']); + + (function() { + var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; + ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; + var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); + })(); + </script> + + </head> + <body> + <!-- magical breadcrumbs --> + <div class="topnav"> + <div class="container"> + <ul class="breadcrumb"> + <li> + <div class="dropdown"> + <a data-toggle="dropdown" href="#">Apache Software Foundation <span class="caret"></span></a> + <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel"> + <li><a href="http://www.apache.org";>Apache Homepage</a></li> + <li><a href="http://www.apache.org/licenses/";>License</a></li> + <li><a href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li> + <li><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li> + <li><a href="http://www.apache.org/security/";>Security</a></li> + </ul> + </div> + </li> + + <li><a href="http://mesos.apache.org";>Apache Mesos</a></li> + + + <li><a href="/documentation +/">Documentation +</a></li> + + + </ul><!-- /.breadcrumb --> + </div><!-- /.container --> + </div><!-- /.topnav --> + + <!-- navbar excitement --> +<div class="navbar navbar-default navbar-static-top" role="navigation"> + <div class="container"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#mesos-menu" aria-expanded="false"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <a class="navbar-brand" href="/"><img src="/assets/img/mesos_logo.png" alt="Apache Mesos logo"/></a> + </div><!-- /.navbar-header --> + + <div class="navbar-collapse collapse" id="mesos-menu"> + <ul class="nav navbar-nav navbar-right"> + <li><a href="/gettingstarted/">Getting Started</a></li> + <li><a href="/blog/">Blog</a></li> + <li><a href="/documentation/latest/">Documentation</a></li> + <li><a href="/downloads/">Downloads</a></li> + <li><a href="/community/">Community</a></li> + </ul> + </div><!-- /#mesos-menu --> + </div><!-- /.container --> +</div><!-- /.navbar --> + +<div class="content"> + <div class="container"> + <div class="row-fluid"> + <div class="col-md-4"> + <h4>If you're new to Mesos</h4> + <p>See the <a href="/gettingstarted/">getting started</a> page for more + information about downloading, building, and deploying Mesos.</p> + + <h4>If you'd like to get involved or you're looking for support</h4> + <p>See our <a href="/community/">community</a> page for more details.</p> + </div> + <div class="col-md-8"> + <h1>Adding a new library or executable</h1> + +<p>When adding a new library or executable, prefer using the name directly as the +target. E.g. <code>libprocess</code> is <code>add_library(process)</code>, and <code>mesos-agent</code> is +<code>add_executable(mesos-agent)</code>. Note that, on platforms where it is conventional, +<code>add_library</code> will prepend <code>lib</code> when writing the library to disk.</p> + +<p>Do not introduce a variable simply to hold the name of the target; if the name +on disk needs to be a specific value, set the target property <code>OUTPUT_NAME</code>.</p> + +<h1>Adding a third-party dependency</h1> + +<p>When adding a third-party dependency, keep the principle of locality in mind. +All necessary data for building with and linking to the library should +be defined where the library is imported. A consumer of the dependency should +only have to add <code>target_link_libraries(consumer dependency)</code>, with every other +build property coming from the graph (library location, include directories, +compiler definitions, etc.).</p> + +<p>The steps to add a new third-party dependency are:</p> + +<ol> +<li> Add the version and SHA256 hash to <code>Versions.cmake</code>.</li> +<li> Add the URL/tarball file to the top of <code>3rdparty/CMakeLists.txt</code>.</li> +<li> Find an appropriate location in <code>3rdparty/CMakeLists.txt</code> to declare the + library. Add a nice header with the name, description, and home page.</li> +<li> Use <code>add_library(IMPORTED)</code> to declare an imported target. + A header-only library is imported with <code>add_library(INTERFACE)</code>.</li> +<li> Use <a href="https://cmake.org/cmake/help/latest/module/ExternalProject.html";><code>ExternalProject_Add</code></a> to obtain, configure, and build the library.</li> +<li> Link the consumer to the dependency.</li> +</ol> + + +<h2><code>INTERFACE</code> libraries</h2> + +<p>Using header-only libraries in CMake is a breeze. The special <code>INTERFACE</code> +library lets you declare a header-only library as a proper CMake target, and +then use it like any other library. Let’s look at Boost for an example.</p> + +<p>First, we add two lines to <code>Versions.cmake</code>:</p> + +<pre><code>set(BOOST_VERSION "1.53.0") +set(BOOST_HASH "SHA256=CED7CE2ED8D7D34815AC9DB1D18D28FCD386FFBB3DE6DA45303E1CF193717038") +</code></pre> + +<p>This lets us keep the versions (and the SHA256 hash of the tarball) of all our +third-party dependencies in one location.</p> + +<p>Second, we add one line to the top of <code>3rdparty/CMakeLists.txt</code> to declare the +location of the tarball:</p> + +<pre><code>set(BOOST_URL ${FETCH_URL}/boost-${BOOST_VERSION}.tar.gz) +</code></pre> + +<p>The <code>FETCH_URL</code> variable lets the <code>REBUNDLED</code> option switch between offline and +online versions. The use of <code>BOOST_VERSION</code> shows why this variable is declared +early; it’s used a few times.</p> + +<p>Third, we find a location in <code>3rdparty/CMakeLists.txt</code> to declare the Boost +library.</p> + +<pre><code># Boost: C++ Libraries. +# http://www.boost.org +####################### +... +</code></pre> + +<p>We start with a proper header naming and describing the library, complete with +its home page URL. This is for other developers to easily identify why this +third-party dependency exists.</p> + +<pre><code>... +EXTERNAL(boost ${BOOST_VERSION} ${CMAKE_CURRENT_BINARY_DIR}) +add_library(boost INTERFACE) +add_dependencies(boost ${BOOST_TARGET}) +target_include_directories(boost SYSTEM INTERFACE ${BOOST_ROOT}) +... +</code></pre> + +<p>Fourth, we declare the Boost target.</p> + +<p>To make things easier, we invoke our custom CMake function <code>EXTERNAL</code> to setup +some variables for us: <code>BOOST_TARGET</code>, <code>BOOST_ROOT</code>, and <code>BOOST_CMAKE_ROOT</code>. See +<a href="/documentation/latest/./cmake/#EXTERNAL">the docs</a> for more explanation of <code>EXTERNAL</code>.</p> + +<p>Then we call <code>add_library(boost INTERFACE)</code>. This creates a header-only CMake +target, usable like any other library. We use <code>add_dependencies(boost +${BOOST_TARGET})</code> to add a manual dependency on the <code>ExternalProject_Add</code> step; +this is necessary as CMake is lazy and won’t execute code unless it must (say, +because of a dependency). The final part of creating this header-only library in +our build system is <code>target_include_directories(boost SYSTEM INTERFACE +${BOOST_ROOT})</code>, which sets the <code>BOOST_ROOT</code> folder (the destination of the +extracted headers) as the include interface for the <code>boost</code> target. All +dependencies on Boost will now automatically include this folder during +compilation.</p> + +<p>Fifth, we setup the <code>ExternalProject_Add</code> step. This CMake module is incredibly +flexible, but we’re using it in the simplest case.</p> + +<pre><code>... +ExternalProject_Add( + ${BOOST_TARGET} + PREFIX ${BOOST_CMAKE_ROOT} + CONFIGURE_COMMAND ${CMAKE_NOOP} + BUILD_COMMAND ${CMAKE_NOOP} + INSTALL_COMMAND ${CMAKE_NOOP} + URL ${BOOST_URL} + URL_HASH ${BOOST_HASH}) +</code></pre> + +<p>The name of the custom target this creates is <code>BOOST_TARGET</code>, and the prefix +directory for all the subsequent steps is <code>BOOST_CMAKE_ROOT</code>. Because this is a +header-only library, and <code>ExternalProject_Add</code> defaults to invoking <code>cmake</code>, we +use <code>CMAKE_NOOP</code> to disable the configure, build, and install commands. See <a href="/documentation/latest/./cmake/#cmake_noop">the +docs</a> for more explanation of <code>CMAKE_NOOP</code>. Thus this code +will simply verify the tarball with <code>BOOST_HASH</code>, and then extract it from +<code>BOOST_URL</code> to <code>BOOST_ROOT</code> (a sub-folder of <code>BOOST_CMAKE_ROOT</code>).</p> + +<p>Sixth, and finally, we link <code>stout</code> to <code>boost</code>. This is the <em>only</em> change +necessary to <code>3rdparty/stout/CMakeLists.txt</code>, as the include directory +information is embedded in the CMake graph.</p> + +<pre><code>target_link_libraries( + stout INTERFACE + ... + boost + ...) +</code></pre> + +<p>This dependency need not be specified again, as <code>libprocess</code> and <code>libmesos</code> link +to <code>stout</code>, and so <code>boost</code> is picked up transitively.</p> + +<h3>Stout</h3> + +<p>Stout is a header-only library. Like Boost, it is a real CMake target, declared +in <code>3rdparty/stout/CMakeLists.txt</code>, just without the external bits.</p> + +<pre><code>add_library(stout INTERFACE) +target_include_directories(stout INTERFACE include) +target_link_libraries( + stout INTERFACE + apr + boost + curl + elfio + glog + ...) +</code></pre> + +<p>It is added as an <code>INTERFACE</code> library. Its include directory is specified as an +<code>INTERFACE</code> (the <code>PUBLIC</code> property cannot be used as the library itself is just +an interface). Its “link” dependencies (despite not being a real, linkable +library) are specified as an <code>INTERFACE</code>.</p> + +<p>This notion of an interface in the CMake dependency graph is what makes the +build system reasonable. The Mesos library and executables, and <code>libprocess</code>, do +not have to repeat these lower level dependencies that come from <code>stout</code>.</p> + +<h2><code>IMPORTED</code> libraries</h2> + +<p>Third-party dependencies that we build are only more complicated because we have +to encode their build steps too. We’ll examine <code>glog</code>, and go over the +differences from the interface library <code>boost</code>.</p> + +<p>Notably, when we declare the library, we use:</p> + +<pre><code>add_library(glog ${LIBRARY_LINKAGE} IMPORTED GLOBAL) +</code></pre> + +<p>Instead of <code>INTERFACE</code> we specify <code>IMPORTED</code> as it is an actual library. We add +<code>GLOBAL</code> to enable our pre-compiled header module <code>cotire</code> to find the targets +(as they would otherwise be scoped only to <code>3rdparty</code> and below). And most +oddly, we use <code>${LIBRARY_LINKAGE}</code> to set it as <code>SHARED</code> or <code>STATIC</code> based on +<code>BUILD_SHARED_LIBS</code>, as we can build this dependency in both manners. See <a href="/documentation/latest/./cmake/#library_linkage">the +docs</a> for more information.</p> + +<p>We must patch our bundled version of <code>glog</code> so we call:</p> + +<pre><code>PATCH_CMD(GLOG_PATCH_CMD glog-${GLOG_VERSION}.patch) +</code></pre> + +<p>This generates a patch command. See <a href="/documentation/latest/./cmake/#patch_cmd">the docs</a> for more +information.</p> + +<p>This library is an example of where we differ on Windows and other platforms. On +Windows, we build <code>glog</code> with CMake, and have several properties we must set:</p> + +<pre><code>set_target_properties( + glog PROPERTIES + IMPORTED_LOCATION_DEBUG ${GLOG_ROOT}-build/Debug/glog${LIBRARY_SUFFIX} + IMPORTED_LOCATION_RELEASE ${GLOG_ROOT}-build/Release/glog${LIBRARY_SUFFIX} + IMPORTED_IMPLIB_DEBUG ${GLOG_ROOT}-build/Debug/glog${CMAKE_IMPORT_LIBRARY_SUFFIX} + IMPORTED_IMPLIB_RELEASE ${GLOG_ROOT}-build/Release/glog${CMAKE_IMPORT_LIBRARY_SUFFIX} + INTERFACE_INCLUDE_DIRECTORIES ${GLOG_ROOT}/src/windows + # TODO(andschwa): Remove this when glog is updated. + IMPORTED_LINK_INTERFACE_LIBRARIES DbgHelp + INTERFACE_COMPILE_DEFINITIONS "${GLOG_COMPILE_DEFINITIONS}") +</code></pre> + +<p>The location of an imported library <em>must</em> be set for the build system to link +to it. There is no notion of search through link directories for imported +libraries.</p> + +<p>Windows requires both the <code>DEBUG</code> and <code>RELEASE</code> locations of the library +specified, and since we have (experimental) support to build <code>glog</code> as a shared +library on Windows, we also have to declare the <code>IMPLIB</code> location. Fortunately, +these locations are programmatic based of <code>GLOG_ROOT</code>, set from our call to +<code>EXTERNAL</code>.</p> + +<p>Note that we cannot use <code>target_include_directories</code> with an imported target. We +have to set <code>INTERFACE_INCLUDE_DIRECTORIES</code> manually instead.</p> + +<p>This version of <code>glog</code> on Windows depends on <code>DbgHelp</code> but does not use a +<code>#pragma</code> to include it, so we set it as an interface library that must also be +linked, using the <code>IMPORTED_LINK_INTERFACE_LIBRARIES</code> property.</p> + +<p>For Windows there are multiple compile definitions that must be set when +building with the <code>glog</code> headers, these are specified with the +<code>INTERFACE_COMPILE_DEFINITIONS</code> property.</p> + +<p>For non-Windows platforms, we just set the Autotools commands to configure, +make, and install <code>glog</code>. These commands depend on the project requirements. We +also set the <code>IMPORTED_LOCATION</code> and <code>INTERFACE_INCLUDE_DIRECTORIES</code>.</p> + +<pre><code>set(GLOG_CONFIG_CMD ${GLOG_ROOT}/src/../configure --with-pic GTEST_CONFIG=no --prefix=${GLOG_ROOT}-build) +set(GLOG_BUILD_CMD make) +set(GLOG_INSTALL_CMD make install) + +set_target_properties( + glog PROPERTIES + IMPORTED_LOCATION ${GLOG_ROOT}-build/lib/libglog${LIBRARY_SUFFIX} + INTERFACE_INCLUDE_DIRECTORIES ${GLOG_ROOT}-build/include) +</code></pre> + +<p>To work around some issues, we have to call <code>MAKE_INCLUDE_DIR(glog)</code> to create +the include directory immediately so as to satisfy CMake’s requirement that it +exists (it will be populated by <code>ExternalProject_Add</code> during the build, but must +exist first). See <a href="/documentation/latest/./cmake/#make_include_dir">the docs</a> for more information.</p> + +<p>Then call <code>GET_BYPRODUCTS(glog)</code> to create the <code>GLOG_BYPRODUCTS</code> variable, which +is sent to <code>ExternalProject_Add</code> to make the Ninja build generator happy. See +<a href="/documentation/latest/./cmake/#get_byproducts">the docs</a> for more information.</p> + +<pre><code>MAKE_INCLUDE_DIR(glog) +GET_BYPRODUCTS(glog) +</code></pre> + +<p>Like with Boost, we call <code>ExternalProject_Add</code>:</p> + +<pre><code>ExternalProject_Add( + ${GLOG_TARGET} + PREFIX ${GLOG_CMAKE_ROOT} + BUILD_BYPRODUCTS ${GLOG_BYPRODUCTS} + PATCH_COMMAND ${GLOG_PATCH_CMD} + CMAKE_ARGS ${CMAKE_FORWARD_ARGS};-DBUILD_TESTING=OFF + CONFIGURE_COMMAND ${GLOG_CONFIG_CMD} + BUILD_COMMAND ${GLOG_BUILD_CMD} + INSTALL_COMMAND ${GLOG_INSTALL_CMD} + URL ${GLOG_URL} + URL_HASH ${GLOG_HASH}) +</code></pre> + +<p>In contrast to an interface library, we need to send all the build information, +which we set in variables prior. This includes the <code>BUILD_BYPRODUCTS</code>, and the +<code>PATCH_COMMAND</code> as we have to patch <code>glog</code>.</p> + +<p>Since we build <code>glog</code> with CMake on Windows, we have to set <code>CMAKE_ARGS</code> with +the <code>CMAKE_FORWARD_ARGS</code>, and particular to <code>glog</code>, we disable its tests with +<code>-DBUILD_TESTING=OFF</code>, though this is not a canonical CMake option.</p> + +<p>On Linux, we set the config, build, and install commands, and send them too. +These are empty on Windows, so <code>ExternalProject_Add</code> will fallback to using +CMake, as we needed.</p> + +<p>Finally, we add <code>glog</code> to as a link library to <code>stout</code>:</p> + +<pre><code>target_link_libraries( + stout INTERFACE + ... + glog + ...) +</code></pre> + +<p>No other code is necessary, we have completed adding, building, and linking to +<code>glog</code>. The same patterns can be adapted for any other third-party dependency.</p> + +<h1>Building debug or release configurations</h1> + +<p>The default configuration is always <code>Debug</code>, which means with debug symbols and +without (many) optimizations. Of course, when deploying Mesos an optimized +<code>Release</code> build is desired. This is one of the few inconsistencies in CMake, and +it’s due to the difference between so-called “single-configuration generators” +(such as GNU Make) and “multi-configuration generators” (such as Visual Studio).</p> + +<h2>Configuration-time configurations</h2> + +<p>In single-configuration generators, the configuration (debug or release) is +chosen at configuration time (that is, when initially calling <code>cmake</code> to +configure the build), and it is not changeable without re-configuring. So +building a <code>Release</code> configuration on Linux (with GNU Make) is done via:</p> + +<pre><code>cmake -DCMAKE_BUILD_TYPE=Release .. +cmake --build . +</code></pre> + +<h2>Build-time configurations</h2> + +<p>However, the Visual Studio generator on Windows allows the developer to change +the release at build-time, making it a multi-configuration generator. CMake +generates a configuration-agnostic solution (and so <code>CMAKE_BUILD_TYPE</code> is +ignored), and the user switches the configuration when building. This can be +done with the familiar configuration menu in the Visual Studio IDE, or with +CMake via:</p> + +<pre><code>cmake .. +cmake --build . --config Release +</code></pre> + +<p>In the same build folder, a <code>Debug</code> build can also be built, with the binaries +stored in <code>Debug</code> and <code>Release</code> folders respectively. Unfortunately, the current +CMake build explicitly sets the final binary destination directories, and so the +final libraries and executables will overwrite each other when building +different configurations.</p> + +<p>Note that Visual Studio is not the only IDE that uses a multi-configuration +generator, Xcode on Mac OS X does as well. +See <a href="https://issues.apache.org/jira/browse/MESOS-7943";>MESOS-7943</a> for more information.</p> + +<h2>Building with shared or static libraries</h2> + +<p>On Linux, the configuration option <code>-DBUILD_SHARED_LIBS=FALSE</code> can be used to +switch to static libraries where possible. Otherwise Linux builds shared +libraries by default.</p> + +<p>On Windows, static libraries are the default. Building with shared libraries on +Windows is not yet supported, as it requires code change to import symbols +properly.</p> + +<h2>Building with Java</h2> + +<p>When building with Java on Windows, you must add the <a href="https://maven.apache.org/guides/getting-started/windows-prerequisites.html";>Maven</a> build tool to +your path. The <code>JAVA_HOME</code> environment variable must also be manually set. +An installation of the Java SDK can be found form <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html";>Oracle</a>.</p> + +<p>As of this writing, Java 9 is not yet supported, but Java 8 has been tested.</p> + +<p>The Java build defaults to <code>OFF</code> because it is slow, to build the Java +components on Windows, turn it <code>ON</code>:</p> + +<pre><code class="powershell">mkdir build; cd build +$env:PATH += ";C:\...\apache-maven-3.3.9\bin\" +$env:JAVA_HOME = "C:\Program Files\Java\jdk1.8.0_144" +cmake .. -DENABLE_JAVA=ON -DENABLE_LIBEVENT=ON -G "Visual Studio 15 2017 Win64" -T "host=x64" +cmake --build . --target mesos-java +</code></pre> + +<p>Note that the <code>mesos-java</code> library does not have to be manually built; as +<code>libmesos</code> will link it when Java is enabled.</p> + +<p>At runtime, if <code>JAVA_JVM_LIBRARY</code> is not set correctly, it can also be set as an +environment variable, and should be of the form:</p> + +<pre><code>C:\Program Files\Java\jdk1.8.0_144\jre\bin\server\jvm.dll +</code></pre> + +<h2>Building with OpenSSL</h2> + +<p>When building with OpenSSL on Windows, you must build or install a distribution +of OpenSSL for Windows. A commonly chosen distribution is <a href="https://slproweb.com/products/Win32OpenSSL.html";>Shining Light +Productions' OpenSSL</a>.</p> + +<p>As of this writing, OpenSSL 1.1.x is not yet supported, but 1.0.2L has been +tested.</p> + +<p>Use <code>-DENABLE_SSL=ON</code> when running CMake to build with OpenSSL.</p> + + </div> +</div> + + </div><!-- /.container --> +</div><!-- /.content --> + +<hr> + + + + <!-- footer --> + <div class="footer"> + <div class="container"> + <div class="col-md-4 social-blk"> + <span class="social"> + <a href="https://twitter.com/ApacheMesos"; + class="twitter-follow-button" + data-show-count="false" data-size="large">Follow @ApacheMesos</a> + <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script> + <a href="https://twitter.com/intent/tweet?button_hashtag=mesos"; + class="twitter-hashtag-button" + data-size="large" + data-related="ApacheMesos">Tweet #mesos</a> + <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script> + </span> + </div> + + <div class="col-md-8 trademark"> + <p>© 2012-2017 <a href="http://apache.org";>The Apache Software Foundation</a>. + Apache Mesos, the Apache feather logo, and the Apache Mesos project logo are trademarks of The Apache Software Foundation. + <p> + </div> + </div><!-- /.container --> + </div><!-- /.footer --> + + <!-- JS --> + <script src="//code.jquery.com/jquery-1.11.0.min.js" type="text/javascript"></script> + <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js" type="text/javascript"></script> + </body> +</html> http://git-wip-us.apache.org/repos/asf/mesos-site/blob/a5fb0e1c/content/documentation/cmake/index.html ---------------------------------------------------------------------- diff --git a/content/documentation/cmake/index.html b/content/documentation/cmake/index.html new file mode 100644 index 0000000..bd92426 --- /dev/null +++ b/content/documentation/cmake/index.html @@ -0,0 +1,514 @@ +<!DOCTYPE html> +<html> + <head> + <meta charset="utf-8"> + <title>Apache Mesos - CMake</title> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + + <meta property="og:locale" content="en_US"/> + <meta property="og:type" content="website"/> + <meta property="og:title" content="Apache Mesos"/> + <meta property="og:site_name" content="Apache Mesos"/> + <meta property="og:url" content="http://mesos.apache.org/"/> + <meta property="og:image" content="http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/> + <meta property="og:description" + content="Apache Mesos abstracts resources away from machines, + enabling fault-tolerant and elastic distributed systems + to easily be built and run effectively."/> + + <meta name="twitter:card" content="summary"/> + <meta name="twitter:site" content="@ApacheMesos"/> + <meta name="twitter:title" content="Apache Mesos"/> + <meta name="twitter:image" content="http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/> + <meta name="twitter:description" + content="Apache Mesos abstracts resources away from machines, + enabling fault-tolerant and elastic distributed systems + to easily be built and run effectively."/> + + <link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet"> + <link rel="alternate" type="application/atom+xml" title="Apache Mesos Blog" href="/blog/feed.xml"> + <link href="../../assets/css/main.css" media="screen" rel="stylesheet" type="text/css" /> + + + + <!-- Google Analytics Magic --> + <script type="text/javascript"> + var _gaq = _gaq || []; + _gaq.push(['_setAccount', 'UA-20226872-1']); + _gaq.push(['_setDomainName', 'apache.org']); + _gaq.push(['_trackPageview']); + + (function() { + var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; + ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; + var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); + })(); + </script> + + </head> + <body> + <!-- magical breadcrumbs --> + <div class="topnav"> + <div class="container"> + <ul class="breadcrumb"> + <li> + <div class="dropdown"> + <a data-toggle="dropdown" href="#">Apache Software Foundation <span class="caret"></span></a> + <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel"> + <li><a href="http://www.apache.org";>Apache Homepage</a></li> + <li><a href="http://www.apache.org/licenses/";>License</a></li> + <li><a href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li> + <li><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li> + <li><a href="http://www.apache.org/security/";>Security</a></li> + </ul> + </div> + </li> + + <li><a href="http://mesos.apache.org";>Apache Mesos</a></li> + + + <li><a href="/documentation +/">Documentation +</a></li> + + + </ul><!-- /.breadcrumb --> + </div><!-- /.container --> + </div><!-- /.topnav --> + + <!-- navbar excitement --> +<div class="navbar navbar-default navbar-static-top" role="navigation"> + <div class="container"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#mesos-menu" aria-expanded="false"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <a class="navbar-brand" href="/"><img src="/assets/img/mesos_logo.png" alt="Apache Mesos logo"/></a> + </div><!-- /.navbar-header --> + + <div class="navbar-collapse collapse" id="mesos-menu"> + <ul class="nav navbar-nav navbar-right"> + <li><a href="/gettingstarted/">Getting Started</a></li> + <li><a href="/blog/">Blog</a></li> + <li><a href="/documentation/latest/">Documentation</a></li> + <li><a href="/downloads/">Downloads</a></li> + <li><a href="/community/">Community</a></li> + </ul> + </div><!-- /#mesos-menu --> + </div><!-- /.container --> +</div><!-- /.navbar --> + +<div class="content"> + <div class="container"> + <div class="row-fluid"> + <div class="col-md-4"> + <h4>If you're new to Mesos</h4> + <p>See the <a href="/gettingstarted/">getting started</a> page for more + information about downloading, building, and deploying Mesos.</p> + + <h4>If you'd like to get involved or you're looking for support</h4> + <p>See our <a href="/community/">community</a> page for more details.</p> + </div> + <div class="col-md-8"> + <h1>Install CMake 3.7+</h1> + +<h2>Linux</h2> + +<p>Install the latest version of CMake from <a href="https://cmake.org/download/";>CMake.org</a>. +A self-extracting tarball is available to make this process painless.</p> + +<p>Currently, few of the common Linux flavors package a sufficient CMake +version. Ubuntu versions 12.04 and 14.04 package CMake 2; +Ubuntu 16.04 packages CMake 3.5. If you already installed cmake from packages, +you may remove it via: <code>apt-get purge cmake</code>.</p> + +<p>The standard CentOS package is CMake 2, and unfortunately even the <code>cmake3</code> +package in EPEL is only CMake 3.6, you may remove them via: +<code>yum remove cmake cmake3</code>.</p> + +<h2>Mac OS X</h2> + +<p>HomeBrew’s CMake version is sufficient: <code>brew install cmake</code>.</p> + +<h2>Windows</h2> + +<p>Download and install the MSI from <a href="https://cmake.org/download/";>CMake.org</a>.</p> + +<p><strong>NOTE:</strong> Windows needs CMake 3.8+, rather than 3.7+.</p> + +<h1>Supported options</h1> + +<p>See <a href="/documentation/latest/./configuration/cmake/">configuration options</a>.</p> + +<h1>Examples</h1> + +<p>See <a href="/documentation/latest/./cmake-examples/">CMake By Example</a>.</p> + +<h1>Documentation</h1> + +<p>The <a href="https://cmake.org/cmake/help/latest/";>CMake documentation</a> is written as a reference module. The most commonly +used sections are:</p> + +<ul> +<li><a href="https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html";>buildsystem overview</a></li> +<li><a href="https://cmake.org/cmake/help/latest/manual/cmake-commands.7.html";>commands</a></li> +<li><a href="https://cmake.org/cmake/help/latest/manual/cmake-properties.7.html";>properties</a></li> +<li><a href="https://cmake.org/cmake/help/latest/manual/cmake-variables.7.html";>variables</a></li> +</ul> + + +<p>The wiki also has a set of <a href="https://cmake.org/Wiki/CMake_Useful_Variables";>useful variables</a>.</p> + +<h1>Dependency graph</h1> + +<p>Like any build system, CMake has a dependency graph. The difference is +that targets in CMake’s dependency graph are <em>much richer</em> compared to other +build systems. CMake targets have the notion of ‘interfaces’, where build +properties are saved as part of the target, and these properties can be +inherited transitively within the graph.</p> + +<p>For example, say there is a library <code>mylib</code>, and anything which links it must +include its headers, located in <code>mylib/include</code>. When building the library, some +private headers must also be included, but not when linking to it. When +compiling the executable <code>myprogram</code>, <code>mylib</code>’s public headers must be included, +but not its private headers. There is no manual step to add <code>mylib/include</code> to +<code>myprogram</code> (and any other program which links to <code>mylib</code>), it is instead +deduced from the public interface property of <code>mylib</code>. This is represented by +the following code:</p> + +<pre><code># A new library with a single source file (headers are found automatically). +add_library(mylib mylib.cpp) + +# The folder of private headers, not exposed to consumers of `mylib`. +target_include_directories(mylib PRIVATE mylib/private) + +# The folder of public headers, added to the compilation of any consumer. +target_include_directories(mylib PUBLIC mylib/include) + +# A new exectuable with a single source file. +add_executable(myprogram main.cpp) + +# The creation of the link dependency `myprogram` -> `mylib`. +target_link_libraries(myprogram mylib) + +# There is no additional step to add `mylib/include` to `myprogram`. +</code></pre> + +<p>This same notion applies to practically every build property: +compile definitions via <a href="https://cmake.org/cmake/help/latest/command/target_compile_definitions.html";><code>target_compile_definitions</code></a>, +include directories via <a href="https://cmake.org/cmake/help/latest/command/target_include_directories.html";><code>target_include_directories</code></a>, +link libraries via <a href="https://cmake.org/cmake/help/latest/command/target_link_libraries.html";><code>target_link_libraries</code></a>, +compile options via <a href="https://cmake.org/cmake/help/latest/command/target_compile_options.html";><code>target_compile_options</code></a>, +and compile features via <a href="https://cmake.org/cmake/help/latest/command/target_compile_features.html";><code>target_compile_features</code></a>.</p> + +<p>All of these commands also take an optional argument of +<code><INTERFACE|PUBLIC|PRIVATE></code>, which constrains their transitivity in the graph. +That is, a <code>PRIVATE</code> include directory is recorded for the target, but not +shared transitively to anything depending on the target, <code>PUBLIC</code> is used +for both the target and dependencies on it, and <code>INTERFACE</code> is used only +for dependencies.</p> + +<p>Notably missing from this list are link directories. CMake explicitly prefers +finding and using the absolute paths to libraries, obsoleting link directories.</p> + +<h1>Common mistakes</h1> + +<h2>Booleans</h2> + +<p>CMake treats <code>ON</code>, <code>OFF</code>, <code>TRUE</code>, <code>FALSE</code>, <code>1</code>, and <code>0</code> all as true/false +booleans. Furthermore, variables of the form <code><target>-NOTFOUND</code> are also +treated as false (this is used for finding packages).</p> + +<p>In Mesos, we prefer the boolean types <code>TRUE</code> and <code>FALSE</code>.</p> + +<p>See <a href="https://cmake.org/cmake/help/latest/command/if.html";><code>if</code></a> for more info.</p> + +<h2>Conditionals</h2> + +<p>For historical reasons, CMake conditionals such as <code>if</code> and <code>elseif</code> +automatically interpolate variable names. It is therefore dangerous to +interpolate them manually, because if <code>${FOO}</code> evaluates to <code>BAR</code>, and <code>BAR</code> is +another variable name, then <code>if (${FOO})</code> becomes <code>if (BAR)</code>, and <code>BAR</code> is then +evaluated again by the <code>if</code>. Stick to <code>if (FOO)</code> to check the value of <code>${FOO}</code>. +Do not use <code>if (${FOO})</code>.</p> + +<p>Also see the CMake policies +<a href="https://cmake.org/cmake/help/latest/policy/CMP0012.html";>CMP0012</a> and +<a href="https://cmake.org/cmake/help/latest/policy/CMP0054.html";>CMP0054</a>.</p> + +<h2>Definitions</h2> + +<p>When using <code>add_definitions()</code> (which should be used rarely, as it is for +“global” compile definitions), the flags must be prefixed with <code>-D</code> to be +treated as preprocessor definitions. However, when using +<code>target_compile_definitions()</code> (which should be preferred, as it is +for specific targets), the flags do not need the prefix.</p> + +<h1>Style</h1> + +<p>In general, wrap at 80 lines, and use a two-space indent. When wrapping +arguments, put the command on a separate line and arguments on subsequent lines:</p> + +<pre><code>target_link_libraries( + program PRIVATE + alpha + beta + gamma) +</code></pre> + +<p>Otherwise keep it together:</p> + +<pre><code>target_link_libraries(program PUBLIC library) +</code></pre> + +<p>Always keep the trailing parenthesis with the last argument.</p> + +<p>Use a single space between conditionals and their open parenthesis, e.g. +<code>if (FOO)</code>, but not for commands, e.g. <code>add_executable(program)</code>.</p> + +<p>CAPITALIZE the declaration and use of custom functions and macros (e.g. +<code>EXTERNAL</code> and <code>PATCH_CMD</code>), and do not capitalize the use of CMake built-in +(including modules) functions and macros. CAPITALIZE variables.</p> + +<h1>CMake anti-patterns</h1> + +<p>Because CMake handles much more of the grunt work for you than other build +systems, there are unfortunately a lot of CMake <a href="http://voices.canonical.com/jussi.pakkanen/2013/03/26/a-list-of-common-cmake-antipatterns/";>anti-patterns</a> you should +look out for when writing new CMake code. These are some common problems +that should be avoided when writing new CMake code:</p> + +<h2>Superfluous use of <code>add_dependencies</code></h2> + +<p>When you’ve linked library <code>a</code> to library <code>b</code> with <code>target_link_libraries(a b)</code>, +the CMake graph is already updated with the dependency information. It is +redundant to use <code>add_dependencies(a b)</code> to (re)specify the dependency. In fact, +this command should <em>rarely</em> be used.</p> + +<p>The exceptions to this are:</p> + +<ol> +<li> Setting a dependency from an imported library to a target added via + <code>ExternalProject_Add</code>.</li> +<li> Setting a dependency on Mesos modules since no explicit linking is done.</li> +<li> Setting a dependency between executables (e.g. the <code>mesos-agent</code> requiring the + <code>mesos-containerizer</code> executable). In general, runtime dependencies need + to be setup with <code>add_dependency</code>, but never link dependencies.</li> +</ol> + + +<h2>Use of <code>link_libraries</code> or <code>link_directories</code></h2> + +<p>Neither of these commands should ever be used. The only appropriate command used +to link libraries is <a href="https://cmake.org/cmake/help/latest/command/target_link_libraries.html";><code>target_link_libraries</code></a>, which records the information +in the CMake dependency graph. Furthermore, imported third-party libraries +should have correct locations recorded in their respective targets, so the use +of <code>link_directories</code> should never be necessary. The +<a href="https://cmake.org/cmake/help/latest/command/link_directories.html";>official documentation</a> states:</p> + +<blockquote><p>Note that this command is rarely necessary. Library locations returned by +<code>find_package()</code> and <code>find_library()</code> are absolute paths. Pass these absolute +library file paths directly to the <code>target_link_libraries()</code> command. CMake +will ensure the linker finds them.</p></blockquote> + +<p>The difference is that the former sets global (or directory level) side effects, +and the latter sets specific target information stored in the graph.</p> + +<h2>Use of <code>include_directories</code></h2> + +<p>This is similar to the above: the <a href="https://cmake.org/cmake/help/latest/command/target_include_directories.html";><code>target_include_directories</code></a> should always +be preferred so that the include directory information remains localized to the +appropriate targets.</p> + +<h2>Adding anything to <code>endif ()</code></h2> + +<p>Old versions of CMake expected the style <code>if (FOO) ... endif (FOO)</code>, where the +<code>endif</code> contained the same expression as the <code>if</code> command. However, this is +tortuously redundant, so leave the parentheses in <code>endif ()</code> empty. This goes +for other endings too, such as <code>endforeach ()</code>, <code>endwhile ()</code>, <code>endmacro ()</code> and +<code>endfunction ()</code>.</p> + +<h2>Specifying header files superfluously</h2> + +<p>One of the distinct advantages of using CMake for C and C++ projects is that +adding header files to the source list for a target is unnecessary. CMake is +designed to parse the source files (<code>.c</code>, <code>.cpp</code>, etc.) and determine their +required headers automatically. The exception to this is headers generated as +part of the build (such as protobuf or the JNI headers).</p> + +<h2>Checking <code>CMAKE_BUILD_TYPE</code></h2> + +<p>See the <a href="cmake-examples.md#building-debug-or-release-configurations">“Building debug or release configurations”</a> example for more +information. In short, not all generators respect the variable +<code>CMAKE_BUILD_TYPE</code> at configuration time, and thus it must not be used in CMake +logic. A usable alternative (where supported) is a <a href="https://cmake.org/cmake/help/latest/manual/cmake-generator-expressions.7.html#logical-expressions";>generator expression</a> such +as <code>$<$<CONFIG:Debug>:DEBUG_MODE></code>.</p> + +<h1>Remaining hacks</h1> + +<h2><code>3RDPARTY_DEPENDENCIES</code></h2> + +<p>Until Mesos on Windows is stable, we keep some dependencies in an external +repository, <a href="https://github.com/3rdparty/mesos-3rdparty";>mesos-3rdparty</a>. When +all dependencies are bundled with Mesos, this extra repository will no longer be +necessary. Until then, the CMake variable <code>3RDPARTY_DEPENDENCIES</code> points by +default to this URL, but it can also point to the on-disk location of a local +clone of the repo. With this option you can avoid pulling from GitHub for every +clean build.</p> + +<h2><code>EXTERNAL</code></h2> + +<p>The CMake function <code>EXTERNAL</code> defines a few variables that make it easy for us +to track the directory structure of a dependency. In particular, if our +library’s name is <code>boost</code>, we invoke:</p> + +<pre><code>EXTERNAL(boost ${BOOST_VERSION} ${CMAKE_CURRENT_BINARY_DIR}) +</code></pre> + +<p>Which will define the following variables as side-effects in the current scope:</p> + +<ul> +<li><code>BOOST_TARGET</code> (a target folder name to put dep in e.g., <code>boost-1.53.0</code>)</li> +<li><code>BOOST_CMAKE_ROOT</code> (where to have CMake put the uncompressed source, e.g., + <code>build/3rdparty/boost-1.53.0</code>)</li> +<li><code>BOOST_ROOT</code> (where the code goes in various stages of build, e.g., + <code>build/.../boost-1.53.0/src</code>, which might contain folders + <code>build-1.53.0-build</code>, <code>-lib</code>, and so on, for each build + step that dependency has)</li> +</ul> + + +<p>The implementation is in <code>3rdparty/cmake/External.cmake</code>.</p> + +<p>This is not to be confused with the CMake module <a href="https://cmake.org/cmake/help/latest/module/ExternalProject.html";>ExternalProject</a>, from which +we use <code>ExternalProject_Add</code> to download, extract, configure, and build our +dependencies.</p> + +<h2><code>CMAKE_NOOP</code></h2> + +<p>This is a CMake variable we define in <code>3rdparty/CMakeLists.txt</code> so that we can +cancel steps of <code>ExternalProject</code>. <code>ExternalProject</code>’s default behavior is to +attempt to configure, build, and install a project using CMake. So when one of +these steps must be skipped, we use set it to <code>CMAKE_NOOP</code> so that nothing +is run instead.</p> + +<h2><code>CMAKE_FORWARD_ARGS</code></h2> + +<p>The <code>CMAKE_FORWARD_ARGS</code> variable defined in <code>3rdparty/CMakeLists.txt</code> is sent +as the <code>CMAKE_ARGS</code> argument to the <code>ExternalProject_Add</code> macro (along with any +per-project arguments), and is used when the external project is configured as a +CMake project. If either the <code>CONFIGURE_COMMAND</code> or <code>BUILD_COMMAND</code> arguments of +<code>ExternalProject_Add</code> are used, then the <code>CMAKE_ARGS</code> argument will be ignored. +This variable ensures that compilation configurations are properly propagated to +third-party dependencies, such as compiler flags.</p> + +<h2><code>LIBRARY_LINKAGE</code></h2> + +<p>This variable is a shortcut used in <code>3rdparty/CMakeLists.txt</code>. It is set to +<code>SHARED</code> when <code>BUILD_SHARED_LIBS</code> is true, and otherwise it is set to <code>STATIC</code>. +The <code>SHARED</code> and <code>STATIC</code> keywords are used to declare how a library should be +built; however, if left out then the type is deduced automatically from +<code>BUILD_SHARED_LIBS</code>.</p> + +<h2><code>MAKE_INCLUDE_DIR</code></h2> + +<p>This function works around a <a href="https://gitlab.kitware.com/cmake/cmake/issues/15052";>CMake issue</a> with setting include +directories of imported libraries built with <code>ExternalProject_Add</code>. We have to +call this for each <code>IMPORTED</code> third-party dependency which has set +<code>INTERFACE_INCLUDE_DIRECTORIES</code>, just to make CMake happy. An example is Glog:</p> + +<pre><code>MAKE_INCLUDE_DIR(glog) +</code></pre> + +<h2><code>GET_BYPRODUCTS</code></h2> + +<p>This function works around a <a href="https://cmake.org/pipermail/cmake/2015-April/060234.html";>CMake issue</a> with the Ninja +generator where it does not understand imported libraries, and instead needs +<code>BUILD_BYPRODUCTS</code> explicitly set. This simply allows us to use +<code>ExternalProject_Add</code> and Ninja. For Glog, it looks like this:</p> + +<pre><code>GET_BYPRODUCTS(glog) +</code></pre> + +<p>Also see the CMake policy <a href="https://cmake.org/cmake/help/latest/policy/CMP0058.html";>CMP0058</a>.</p> + +<h2><code>PATCH_CMD</code></h2> + +<p>The CMake function <code>PATCH_CMD</code> generates a patch command given a patch file. +If the path is not absolute, it’s resolved to the current source directory. +It stores the command in the variable name supplied. This is used to easily +patch third-party dependencies. For Glog, it looks like this:</p> + +<pre><code>PATCH_CMD(GLOG_PATCH_CMD glog-${GLOG_VERSION}.patch) +ExternalProject_Add( + ${GLOG_TARGET} + ... + PATCH_COMMAND ${GLOG_PATCH_CMD}) +</code></pre> + +<p>The implementation is in <code>3rdparty/cmake/PatchCommand.cmake</code>.</p> + +<h3>Windows <code>patch.exe</code></h3> + +<p>While using <code>patch</code> on Linux is straightforward, doing the same on Windows takes +a bit of work. <code>PATH_CMD</code> encapsulates this:</p> + +<ul> +<li>Checks the cache variable <code>PATCHEXE_PATH</code> for <code>patch.exe</code>.</li> +<li>Searches for <code>patch.exe</code> in its default locations.</li> +<li>Copies <code>patch.exe</code> and a custom manifest to the temporary directory.</li> +<li>Applies the manifest to avoid the UAC prompt.</li> +<li>Uses the patched <code>patch.exe</code>.</li> +</ul> + + +<p>As such, <code>PATCH_CMD</code> lets us apply patches as we do on Linux, without requiring +an administrative prompt.</p> + +<p>Note that on Windows, the patch file must have CRLF line endings. A file with LF +line endings will cause the error: “Assertion failed, hunk, file patch.c, line +343”. For this reason, it is required to checkout the Mesos repo with <code>git +config core.autocrlf true</code>.</p> + + </div> +</div> + + </div><!-- /.container --> +</div><!-- /.content --> + +<hr> + + + + <!-- footer --> + <div class="footer"> + <div class="container"> + <div class="col-md-4 social-blk"> + <span class="social"> + <a href="https://twitter.com/ApacheMesos"; + class="twitter-follow-button" + data-show-count="false" data-size="large">Follow @ApacheMesos</a> + <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script> + <a href="https://twitter.com/intent/tweet?button_hashtag=mesos"; + class="twitter-hashtag-button" + data-size="large" + data-related="ApacheMesos">Tweet #mesos</a> + <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script> + </span> + </div> + + <div class="col-md-8 trademark"> + <p>© 2012-2017 <a href="http://apache.org";>The Apache Software Foundation</a>. + Apache Mesos, the Apache feather logo, and the Apache Mesos project logo are trademarks of The Apache Software Foundation. + <p> + </div> + </div><!-- /.container --> + </div><!-- /.footer --> + + <!-- JS --> + <script src="//code.jquery.com/jquery-1.11.0.min.js" type="text/javascript"></script> + <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js" type="text/javascript"></script> + </body> +</html> http://git-wip-us.apache.org/repos/asf/mesos-site/blob/a5fb0e1c/content/documentation/configuration-cmake/index.html ---------------------------------------------------------------------- diff --git a/content/documentation/configuration-cmake/index.html b/content/documentation/configuration-cmake/index.html deleted file mode 100644 index ea1f823..0000000 --- a/content/documentation/configuration-cmake/index.html +++ /dev/null @@ -1,259 +0,0 @@ -<!DOCTYPE html> -<html> - <head> - <meta charset="utf-8"> - <title>Apache Mesos - CMake Configuration</title> - <meta name="viewport" content="width=device-width, initial-scale=1.0"> - - <meta property="og:locale" content="en_US"/> - <meta property="og:type" content="website"/> - <meta property="og:title" content="Apache Mesos"/> - <meta property="og:site_name" content="Apache Mesos"/> - <meta property="og:url" content="http://mesos.apache.org/"/> - <meta property="og:image" content="http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/> - <meta property="og:description" - content="Apache Mesos abstracts resources away from machines, - enabling fault-tolerant and elastic distributed systems - to easily be built and run effectively."/> - - <meta name="twitter:card" content="summary"/> - <meta name="twitter:site" content="@ApacheMesos"/> - <meta name="twitter:title" content="Apache Mesos"/> - <meta name="twitter:image" content="http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/> - <meta name="twitter:description" - content="Apache Mesos abstracts resources away from machines, - enabling fault-tolerant and elastic distributed systems - to easily be built and run effectively."/> - - <link href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css" rel="stylesheet"> - <link rel="alternate" type="application/atom+xml" title="Apache Mesos Blog" href="/blog/feed.xml"> - <link href="../../assets/css/main.css" media="screen" rel="stylesheet" type="text/css" /> - - - - <!-- Google Analytics Magic --> - <script type="text/javascript"> - var _gaq = _gaq || []; - _gaq.push(['_setAccount', 'UA-20226872-1']); - _gaq.push(['_setDomainName', 'apache.org']); - _gaq.push(['_trackPageview']); - - (function() { - var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; - ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; - var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); - })(); - </script> - - </head> - <body> - <!-- magical breadcrumbs --> - <div class="topnav"> - <div class="container"> - <ul class="breadcrumb"> - <li> - <div class="dropdown"> - <a data-toggle="dropdown" href="#">Apache Software Foundation <span class="caret"></span></a> - <ul class="dropdown-menu" role="menu" aria-labelledby="dLabel"> - <li><a href="http://www.apache.org";>Apache Homepage</a></li> - <li><a href="http://www.apache.org/licenses/";>License</a></li> - <li><a href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li> - <li><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li> - <li><a href="http://www.apache.org/security/";>Security</a></li> - </ul> - </div> - </li> - - <li><a href="http://mesos.apache.org";>Apache Mesos</a></li> - - - <li><a href="/documentation -/">Documentation -</a></li> - - - </ul><!-- /.breadcrumb --> - </div><!-- /.container --> - </div><!-- /.topnav --> - - <!-- navbar excitement --> -<div class="navbar navbar-default navbar-static-top" role="navigation"> - <div class="container"> - <div class="navbar-header"> - <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#mesos-menu" aria-expanded="false"> - <span class="sr-only">Toggle navigation</span> - <span class="icon-bar"></span> - <span class="icon-bar"></span> - <span class="icon-bar"></span> - </button> - <a class="navbar-brand" href="/"><img src="/assets/img/mesos_logo.png" alt="Apache Mesos logo"/></a> - </div><!-- /.navbar-header --> - - <div class="navbar-collapse collapse" id="mesos-menu"> - <ul class="nav navbar-nav navbar-right"> - <li><a href="/gettingstarted/">Getting Started</a></li> - <li><a href="/blog/">Blog</a></li> - <li><a href="/documentation/latest/">Documentation</a></li> - <li><a href="/downloads/">Downloads</a></li> - <li><a href="/community/">Community</a></li> - </ul> - </div><!-- /#mesos-menu --> - </div><!-- /.container --> -</div><!-- /.navbar --> - -<div class="content"> - <div class="container"> - <div class="row-fluid"> - <div class="col-md-4"> - <h4>If you're new to Mesos</h4> - <p>See the <a href="/gettingstarted/">getting started</a> page for more - information about downloading, building, and deploying Mesos.</p> - - <h4>If you'd like to get involved or you're looking for support</h4> - <p>See our <a href="/community/">community</a> page for more details.</p> - </div> - <div class="col-md-8"> - <h1>Mesos CMake Build Configuration Options</h1> - -<p>Mesos currently exposes two build systems, one written in -<a href="/documentation/latest/./configuration/">autotools</a>, and one written in CMake. -This document describes the configuration flags available in -the CMake build system.</p> - -<h2>CMake configuration options</h2> - -<table class="table table-striped"> - <thead> - <tr> - <th width="30%"> - Flag - </th> - <th> - Explanation - </th> - </tr> - </thead> - <tr> - <td> - -D3RDPARTY_DEPENDENCIES[=path_or_url] - </td> - <td> - Location of the dependency mirror. In some cases, the Mesos build system - needs to acquire third-party dependencies that aren't rebundled as - tarballs in the Mesos repository. For example, on Windows, we must aquire - newer versions of some dependencies, and since Windows does not have a - package manager, we must acquire system dependencies like cURL. This - parameter can be either a URL (for example, pointing at the Mesos official - [third-party dependency mirror](https://github.com/3rdparty/mesos-3rdparty)), - or a local folder (for example, a local clone of the dependency mirror). - [default=https://github.com/3rdparty/mesos-3rdparty] - </td> - </tr> - <tr> - <td> - -DCPACK_BINARY_(BUNDLE|DEB|DRAGNDROP|IFW|NSIS|OSXX11|PACKAGEMAKER|RPM|STGZ|TBZ2|TGZ|TXZ) - </td> - <td> - This modifies the 'package' target to generate binary package of - the specified format. A binary package contains everything that - would be installed via CMake's 'install' target. - [default=OFF] - </td> - </tr> - <tr> - <td> - -DCPACK_SOURCE_(TBZ2|TXZ|TZ|ZIP) - </td> - <td> - This modifies the 'package_source' target to generate a package of the - sources required to build and test Mesos, in the specified format. - [default=OFF] - </td> - </tr> - <tr> - <td> - -DENABLE_LIBEVENT - </td> - <td> - Use libevent instead of libev for the event loop. [default=FALSE] - </td> - </tr> - <tr> - <td> - -DENABLE_SSL - </td> - <td> - Build libprocess with SSL support. [default=FALSE] - </td> - </tr> - <tr> - <td> - -DREBUNDLED - </td> - <td> - Attempt to build against the third-party dependencies included as - tarballs in the Mesos repository. - - NOTE: This is not always possible. For example, a dependency might - not be included as a tarball in the Mesos repository; additionally, - Windows does not have a package manager, so we do not expect system - dependencies like APR to exist natively, and we therefore must acquire - them. In these cases (or when `REBUNDLED` is set to `FALSE`), we will - acquire the dependency from the location specified by the - `3RDPARTY_DEPENDENCIES`, which by default points to the official Mesos - [third-party dependency mirror](https://github.com/3rdparty/mesos-3rdparty). - [default=TRUE] - </td> - </tr> - <tr> - <td> - -DVERBOSE - </td> - <td> - Generate a build solution that produces verbose output - (for example, verbose Makefiles). [default=TRUE] - </td> - </tr> -</table> - - - </div> -</div> - - </div><!-- /.container --> -</div><!-- /.content --> - -<hr> - - - - <!-- footer --> - <div class="footer"> - <div class="container"> - <div class="col-md-4 social-blk"> - <span class="social"> - <a href="https://twitter.com/ApacheMesos"; - class="twitter-follow-button" - data-show-count="false" data-size="large">Follow @ApacheMesos</a> - <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script> - <a href="https://twitter.com/intent/tweet?button_hashtag=mesos"; - class="twitter-hashtag-button" - data-size="large" - data-related="ApacheMesos">Tweet #mesos</a> - <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script> - </span> - </div> - - <div class="col-md-8 trademark"> - <p>© 2012-2017 <a href="http://apache.org";>The Apache Software Foundation</a>. - Apache Mesos, the Apache feather logo, and the Apache Mesos project logo are trademarks of The Apache Software Foundation. - <p> - </div> - </div><!-- /.container --> - </div><!-- /.footer --> - - <!-- JS --> - <script src="//code.jquery.com/jquery-1.11.0.min.js" type="text/javascript"></script> - <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js" type="text/javascript"></script> - </body> -</html>
![http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/](http://mesos.apache.org/assets/img/mesos_logo_fb_preview.png"/){kind=link}