OXIESEC PANEL

Name	Size	Modified	Perms
📁 ..	-	04/04/2023 07:10:48 PM	rwxr-xr-x
📄 A Basic Starting Point.html	44.81 KB	04/04/2023 07:05:07 PM	rw-r--r--
📄 Adding Export Configuration.html	24.5 KB	04/04/2023 07:05:07 PM	rw-r--r--
📄 Adding Generator Expressions.html	34.33 KB	04/04/2023 07:05:07 PM	rw-r--r--
📄 Adding Support for a Testing Dashboard.html	15.39 KB	04/04/2023 07:05:07 PM	rw-r--r--
📄 Adding System Introspection.html	21.8 KB	04/04/2023 07:05:07 PM	rw-r--r--
📄 Adding Usage Requirements for a Library.html	20.26 KB	04/04/2023 07:05:07 PM	rw-r--r--
📄 Adding a Custom Command and Generated File.html	20.66 KB	04/04/2023 07:05:07 PM	rw-r--r--
📄 Adding a Library.html	43.49 KB	04/04/2023 07:05:07 PM	rw-r--r--
📄 Installing and Testing.html	34.32 KB	04/04/2023 07:05:07 PM	rw-r--r--
📄 Packaging Debug and Release.html	14.44 KB	04/04/2023 07:05:07 PM	rw-r--r--
📄 Packaging an Installer.html	12.58 KB	04/04/2023 07:05:07 PM	rw-r--r--
📄 Selecting Static or Shared Libraries.html	32.35 KB	04/04/2023 07:05:07 PM	rw-r--r--
📄 index.html	10.34 KB	04/04/2023 07:05:07 PM	rw-r--r--

Editing: Selecting Static or Shared Libraries.html

<!DOCTYPE html>

<title>Step 10: Selecting Static or Shared Libraries &mdash; CMake 3.26.3 Documentation</title>

</head><body>

<div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../../genindex.html" title="General Index"
 accesskey="I">index</a></li>
 <li class="right" >
 <a href="Adding%20Export%20Configuration.html" title="Step 11: Adding Export Configuration"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="Packaging%20an%20Installer.html" title="Step 9: Packaging an Installer"
 accesskey="P">previous</a> |</li>
 <li>
 <img src="../../_static/cmake-logo-16.png" alt=""
 style="vertical-align: middle; margin-top: -2px" />
 </li>
 <li>
 <a href="https://cmake.org/">CMake</a> &#187;
 </li>
 <li>
 <a href="../../index.html">3.26.3 Documentation</a> &#187;
 </li>

<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">CMake Tutorial</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href="">Step 10: Selecting Static or Shared Libraries</a></li> 
 </ul>
 </div>

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body" role="main">
 
 <section id="step-10-selecting-static-or-shared-libraries">
<h1>Step 10: Selecting Static or Shared Libraries<a class="headerlink" href="#step-10-selecting-static-or-shared-libraries" title="Permalink to this heading">¶</a></h1>
In this section we will show how the <a class="reference internal" href="../../variable/BUILD_SHARED_LIBS.html#variable:BUILD_SHARED_LIBS" title="BUILD_SHARED_LIBS"><code class="xref cmake cmake-variable docutils literal notranslate">BUILD_SHARED_LIBS</code></a> variable can
be used to control the default behavior of <a class="reference internal" href="../../command/add_library.html#command:add_library" title="add_library"><code class="xref cmake cmake-command docutils literal notranslate">add_library()</code></a>,
and allow control over how libraries without an explicit type (<code class="docutils literal notranslate">STATIC</code>,
<code class="docutils literal notranslate">SHARED</code>, <code class="docutils literal notranslate">MODULE</code> or <code class="docutils literal notranslate">OBJECT</code>) are built.
To accomplish this we need to add <a class="reference internal" href="../../variable/BUILD_SHARED_LIBS.html#variable:BUILD_SHARED_LIBS" title="BUILD_SHARED_LIBS"><code class="xref cmake cmake-variable docutils literal notranslate">BUILD_SHARED_LIBS</code></a> to the
top-level <code class="docutils literal notranslate">CMakeLists.txt</code>. We use the <a class="reference internal" href="../../command/option.html#command:option" title="option"><code class="xref cmake cmake-command docutils literal notranslate">option()</code></a> command as it allows
users to optionally select if the value should be <code class="docutils literal notranslate">ON</code> or <code class="docutils literal notranslate">OFF</code>.
Next we are going to refactor <code class="docutils literal notranslate">MathFunctions</code> to become a real library that
encapsulates using <code class="docutils literal notranslate">mysqrt</code> or <code class="docutils literal notranslate">sqrt</code>, instead of requiring the calling
code to do this logic. This will also mean that <code class="docutils literal notranslate">USE_MYMATH</code> will not control
building <code class="docutils literal notranslate">MathFunctions</code>, but instead will control the behavior of this
library.
The first step is to update the starting section of the top-level
<code class="docutils literal notranslate">CMakeLists.txt</code> to look like:
<div class="literal-block-wrapper docutils container" id="cmakelists-txt-option-build-shared-libs">
<div class="code-block-caption">CMakeLists.txt<a class="headerlink" href="#cmakelists-txt-option-build-shared-libs" title="Permalink to this code">¶</a></div>
<div class="highlight-cmake notranslate"><div class="highlight"><pre>cmake_minimum_required(VERSION 3.15)

# set the project name and version
project(Tutorial VERSION 1.0)

# specify the C++ standard
add_library(tutorial_compiler_flags INTERFACE)
target_compile_features(tutorial_compiler_flags INTERFACE cxx_std_11)

# add compiler warning flags just when building this project via
# the BUILD_INTERFACE genex
set(gcc_like_cxx &quot;$&lt;COMPILE_LANG_AND_ID:CXX,ARMClang,AppleClang,Clang,GNU,LCC&gt;&quot;)
set(msvc_cxx &quot;$&lt;COMPILE_LANG_AND_ID:CXX,MSVC&gt;&quot;)
target_compile_options(tutorial_compiler_flags INTERFACE
 &quot;$&lt;${gcc_like_cxx}:$&lt;BUILD_INTERFACE:-Wall;-Wextra;-Wshadow;-Wformat=2;-Wunused&gt;&gt;&quot;
 &quot;$&lt;${msvc_cxx}:$&lt;BUILD_INTERFACE:-W3&gt;&gt;&quot;
)

# control where the static and shared libraries are built so that on windows
# we don&#39;t need to tinker with the path to run the executable
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY &quot;${PROJECT_BINARY_DIR}&quot;)
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY &quot;${PROJECT_BINARY_DIR}&quot;)
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY &quot;${PROJECT_BINARY_DIR}&quot;)

option(BUILD_SHARED_LIBS &quot;Build using shared libraries&quot; ON)

# configure a header file to pass the version number only
configure_file(TutorialConfig.h.in TutorialConfig.h)

# add the MathFunctions library
add_subdirectory(MathFunctions)

# add the executable
add_executable(Tutorial tutorial.cxx)
target_link_libraries(Tutorial PUBLIC MathFunctions tutorial_compiler_flags)
</pre></div>
</div>
</div>
Now that we have made <code class="docutils literal notranslate">MathFunctions</code> always be used, we will need to update
the logic of that library. So, in <code class="docutils literal notranslate">MathFunctions/CMakeLists.txt</code> we need to
create a SqrtLibrary that will conditionally be built and installed when
<code class="docutils literal notranslate">USE_MYMATH</code> is enabled. Now, since this is a tutorial, we are going to
explicitly require that SqrtLibrary is built statically.
The end result is that <code class="docutils literal notranslate">MathFunctions/CMakeLists.txt</code> should look like:
<div class="literal-block-wrapper docutils container" id="mathfunctions-cmakelists-txt-add-library-static">
<div class="code-block-caption">MathFunctions/CMakeLists.txt<a class="headerlink" href="#mathfunctions-cmakelists-txt-add-library-static" title="Permalink to this code">¶</a></div>
<div class="highlight-cmake notranslate"><div class="highlight"><pre># add the library that runs
add_library(MathFunctions MathFunctions.cxx)

# state that anybody linking to us needs to include the current source dir
# to find MathFunctions.h, while we don&#39;t.
target_include_directories(MathFunctions
 INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}
 )

# should we use our own math functions
option(USE_MYMATH &quot;Use tutorial provided math implementation&quot; ON)
if(USE_MYMATH)

target_compile_definitions(MathFunctions PRIVATE &quot;USE_MYMATH&quot;)

# first we add the executable that generates the table
 add_executable(MakeTable MakeTable.cxx)
 target_link_libraries(MakeTable PRIVATE tutorial_compiler_flags)

# add the command to generate the source code
 add_custom_command(
 OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/Table.h
 COMMAND MakeTable ${CMAKE_CURRENT_BINARY_DIR}/Table.h
 DEPENDS MakeTable
 )

# library that just does sqrt
 add_library(SqrtLibrary STATIC
 mysqrt.cxx
 ${CMAKE_CURRENT_BINARY_DIR}/Table.h
 )

# state that we depend on our binary dir to find Table.h
 target_include_directories(SqrtLibrary PRIVATE
 ${CMAKE_CURRENT_BINARY_DIR}
 )

target_link_libraries(SqrtLibrary PUBLIC tutorial_compiler_flags)
 target_link_libraries(MathFunctions PRIVATE SqrtLibrary)
endif()

target_link_libraries(MathFunctions PUBLIC tutorial_compiler_flags)

# define the symbol stating we are using the declspec(dllexport) when
# building on windows
target_compile_definitions(MathFunctions PRIVATE &quot;EXPORTING_MYMATH&quot;)

# install libs
set(installable_libs MathFunctions tutorial_compiler_flags)
if(TARGET SqrtLibrary)
 list(APPEND installable_libs SqrtLibrary)
endif()
install(TARGETS ${installable_libs} DESTINATION lib)
# install include headers
install(FILES MathFunctions.h DESTINATION include)
</pre></div>
</div>
</div>
Next, update <code class="docutils literal notranslate">MathFunctions/mysqrt.cxx</code> to use the <code class="docutils literal notranslate">mathfunctions</code> and
<code class="docutils literal notranslate">detail</code> namespaces:
<div class="literal-block-wrapper docutils container" id="mathfunctions-mysqrt-cxx-namespace">
<div class="code-block-caption">MathFunctions/mysqrt.cxx<a class="headerlink" href="#mathfunctions-mysqrt-cxx-namespace" title="Permalink to this code">¶</a></div>
<div class="highlight-c++ notranslate"><div class="highlight"><pre>#include &lt;iostream&gt;

#include &quot;MathFunctions.h&quot;

// include the generated table
#include &quot;Table.h&quot;

// use the table to help find an initial value
 double result = x;
 if (x &gt;= 1 &amp;&amp; x &lt; 10) {
 std::cout &lt;&lt; &quot;Use the table to help find an initial value &quot; &lt;&lt; std::endl;
 result = sqrtTable[static_cast&lt;int&gt;(x)];
 }

// do ten iterations
 for (int i = 0; i &lt; 10; ++i) {
 if (result &lt;= 0) {
 result = 0.1;
 }
 double delta = x - (result * result);
 result = result + 0.5 * delta / result;
 std::cout &lt;&lt; &quot;Computing sqrt of &quot; &lt;&lt; x &lt;&lt; &quot; to be &quot; &lt;&lt; result &lt;&lt; std::endl;
 }

return result;
}
}
}
</pre></div>
</div>
</div>
We also need to make some changes in <code class="docutils literal notranslate">tutorial.cxx</code>, so that it no longer
uses <code class="docutils literal notranslate">USE_MYMATH</code>:
<ol class="arabic simple">
<li>Always include <code class="docutils literal notranslate">MathFunctions.h</code></li>
<li>Always use <code class="docutils literal notranslate">mathfunctions::sqrt</code></li>
<li>Don't include <code class="docutils literal notranslate">cmath</code></li>
</ol>
Finally, update <code class="docutils literal notranslate">MathFunctions/MathFunctions.h</code> to use dll export defines:
<div class="literal-block-wrapper docutils container" id="mathfunctions-mathfunctions-h">
<div class="code-block-caption">MathFunctions/MathFunctions.h<a class="headerlink" href="#mathfunctions-mathfunctions-h" title="Permalink to this code">¶</a></div>
<div class="highlight-c++ notranslate"><div class="highlight"><pre>#if defined(_WIN32)
# if defined(EXPORTING_MYMATH)
# define DECLSPEC __declspec(dllexport)
# else
# define DECLSPEC __declspec(dllimport)
# endif
#else // non windows
# define DECLSPEC
#endif

namespace mathfunctions {
double DECLSPEC sqrt(double x);
}
</pre></div>
</div>
</div>
At this point, if you build everything, you may notice that linking fails
as we are combining a static library without position independent code with a
library that has position independent code. The solution to this is to
explicitly set the <a class="reference internal" href="../../prop_tgt/POSITION_INDEPENDENT_CODE.html#prop_tgt:POSITION_INDEPENDENT_CODE" title="POSITION_INDEPENDENT_CODE"><code class="xref cmake cmake-prop_tgt docutils literal notranslate">POSITION_INDEPENDENT_CODE</code></a> target property of
SqrtLibrary to be <code class="docutils literal notranslate">True</code> when building shared libraries.
<div class="literal-block-wrapper docutils container" id="mathfunctions-cmakelists-txt-position-independent-code">
<div class="code-block-caption">MathFunctions/CMakeLists.txt<a class="headerlink" href="#mathfunctions-cmakelists-txt-position-independent-code" title="Permalink to this code">¶</a></div>
<div class="highlight-cmake notranslate"><div class="highlight"><pre> # state that SqrtLibrary need PIC when the default is shared libraries
 set_target_properties(SqrtLibrary PROPERTIES
 POSITION_INDEPENDENT_CODE ${BUILD_SHARED_LIBS}
 )
</pre></div>
</div>
</div>
Exercise: We modified <code class="docutils literal notranslate">MathFunctions.h</code> to use dll export defines.
Using CMake documentation can you find a helper module to simplify this?
</section>

<div class="clearer"></div>
 </div>
 </div>
 </div>
 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 <div class="sphinxsidebarwrapper">
 <div>
 <h4>Previous topic</h4>
 <a href="Packaging%20an%20Installer.html"
 title="previous chapter">Step 9: Packaging an Installer</a>
 </div>
 <div>
 <h4>Next topic</h4>
 <a href="Adding%20Export%20Configuration.html"
 title="next chapter">Step 11: Adding Export Configuration</a>
 </div>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="../../_sources/guide/tutorial/Selecting Static or Shared Libraries.rst.txt"
 rel="nofollow">Show Source</a></li>
 </ul>
 </div>
<div id="searchbox" style="display: none" role="search">
 <h3 id="searchlabel">Quick search</h3>
 <div class="searchformwrapper">
 <form class="search" action="../../search.html" method="get">
 <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
 <input type="submit" value="Go" />
 </form>
 </div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
 </div>
 </div>
 <div class="clearer"></div>
 </div>
 <div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../../genindex.html" title="General Index"
 >index</a></li>
 <li class="right" >
 <a href="Adding%20Export%20Configuration.html" title="Step 11: Adding Export Configuration"
 >next</a> |</li>
 <li class="right" >
 <a href="Packaging%20an%20Installer.html" title="Step 9: Packaging an Installer"
 >previous</a> |</li>
 <li>
 <img src="../../_static/cmake-logo-16.png" alt=""
 style="vertical-align: middle; margin-top: -2px" />
 </li>
 <li>
 <a href="https://cmake.org/">CMake</a> &#187;
 </li>
 <li>
 <a href="../../index.html">3.26.3 Documentation</a> &#187;
 </li>

<li class="nav-item nav-item-1"><a href="index.html" >CMake Tutorial</a> &#187;</li>
 <li class="nav-item nav-item-this"><a href="">Step 10: Selecting Static or Shared Libraries</a></li> 
 </ul>
 </div>

<div class="footer" role="contentinfo">
 &#169; Copyright 2000-2023 Kitware, Inc. and Contributors.
 Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.0.2.
 </div>
 </body>
</html>