title: CMake: create_symlink vs ln
body: <p>I have a macro to create links E.g.</p>
  <pre><code>makeLink($BUILD_ROOT/lib somewhere/somelibrary.so makelinks)
  </code></pre>
  <p>The purpose of this is so that a completed build includes a directory structure analogous to a developers installation with <em>bin</em>, <em>include</em> &amp; <em>lib</em> directories containing links to the actual products.</p>
  <p><em>However, the purpose is not relevant to my question which is about create_symlink and not a meta-question about whether links should be used for this or any other purpose.</em></p>
  <p>The macro can be implemented in several ways including:</p>
  <pre><code>macro(makeLink src dest target)
    add_custom_command(TARGET ${target} PRE_BUILD
      COMMAND ln -sf ${src} ${dest} DEPENDS ${dest} COMMENT &quot;mklink ${src} -&gt; ${dest}&quot;)
  endmacro()
  </code></pre>
  <p>or:</p>
  <pre><code>macro(makeLink src dest target)
   add_custom_command(TARGET ${target} PRE_BUILD
     COMMAND ${CMAKE_COMMAND} -E create_symlink ${src} ${dest} DEPENDS  ${dest} COMMENT &quot;mklink ${src} -&gt; ${dest}&quot;)
  endmacro()
  </code></pre>
  <p>Now I understand the point of create_symlink is to be portable in case the platform doesn't understand links. However it seems to be functionally incomplete. There are several different use cases with <em>ln</em></p>
  <ul>
  <li>create a link whether the source exists yet or not</li>
  <li>create a link only if the source exists</li>
  <li>overwrite an existing link or not</li>
  </ul>
  <p>As far as I can see the cmake documentation under-specifies the behaviour (its actually: create the link if the destination doesn't exist and the source exists. Fail if the source doesn't exist)</p>
  <p><a href="https://cmake.org/cmake/help/v3.2/manual/cmake.1.html" rel="nofollow noreferrer">https://cmake.org/cmake/help/v3.2/manual/cmake.1.html</a></p>
  <p>This seems possibly to confuse many users who think it ought to work according to one and only one of the possibly use cases. E.g.</p>
  <p><a href="https://cmake.org/Bug/view.php?id=14928" rel="nofollow noreferrer">https://cmake.org/Bug/view.php?id=14928</a>
  <a href="https://cmake.org/Bug/print_bug_page.php?bug_id=4418" rel="nofollow noreferrer">https://cmake.org/Bug/print_bug_page.php?bug_id=4418</a></p>
  <p><em>Given this why should anyone ever use create_symlink?
  Wouldn't the sensible course be to incorporate support for all the common use cases (essentially by implementing a system portable wrapper to ln)?</em>
  <strong>Is there a semi-standard .cmake file for this somewhere?</strong></p>
  <p>Also is cmake really doing a recursive call to fork itself when you use cmake -E or does the parser recognise it as a special case. I suspect the latter as seems very fast (granted creating links this way would still seem fast) but if that's so why the unnecessarily verbose syntax?</p>
  <hr />
  <p>Note: I am not building the libraries as part of configure. <em>links</em> to libraries are created to support two things:</p>
  <ul>
  <li>linking programs that use the libraries in other sub-projects</li>
  <li>running tests that use the libraries</li>
  </ul>
  <p>The libraries are not actually being built during the 'configure' stage. The links only need to be available just in time. This is part of a migration from a configure/make based build system to cmake/ninja. Its a largish project where a phased roll out of cmake is preferable to a big bang. It just so happens that in the existing system the links are made at configure time (though not used until build time).</p>