[CMake] EXECUTABLE_OUTPUT_PATH is not just deprecated, it's harmful!

[Brad King]

kent williams wrote:
> So we have a big program (well a couple of them Brains2 and Brains3),
> and a bunch of 'unbundled' programs (BRAINSFit, BRAINSDemonWarp,
> BRAINSTracer etc..).
> 
> We use SVN to add the 'unbundled' programs as subdirectories of our
> BRAINS svn checkout.
> 
> So our CMakeLists.txt files in our unbundled programs MUST work
> properly as a standalone build, or as a sub-directory of BRAINS.
> 
> We've done this, at the cost of some slight added complexity in the
> unbundled CMakeLists.txt.  But one thing has REALLY been kicking my
> butt since CMake 2.6 -- they each set EXECUTABLE_OUTPUT_PATH, relative
> to their own CMAKE_CURRENT_BINARY_DIR
> 
> The problem? If you're running standalone, everything's fine. If
> you're building inside the BRAINS tree, though, the LAST
> CMakeLists.txt file in the directory tree that sets
> EXECUTABLE_OUTPUT_PATH wins, and consequently executable files end up
> unexpected places.

What code are you using to set it?  If it doesn't get cached then each
directory should use its own value.  The only reason to cache it is if
you want the user to be able to edit the value at CMake time.

> So I've had to go through and change everywhere that variable occurs
> with CMAKE_RUNTIME_OUTPUT_DIRECTORY, and replace LIBRARY_OUTPUT_PATH
> with CMAKE_LIBRARY_OUTPUT_DIRECTORY.
> 
> Now, ideally, you should be able set those CMAKE_*_OUTPUT_DIRECTORY
> variables in your top level Makefile, and then the path properties for
> targets are set, and everybody's happy.
> 
> But this isn't the case with, for example ADD_TEST.  ADD_TEST will
> search for the named executable in a number of places, but not,
> apparently, in CMAKE_RUNTIME_OUTPUT_DIRECTORY.  So you must do your
> add test like this
> 
> add_test(gumby ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/gumbyTest args)

FYI, I've been working on a new signature for add_test that automatically
recognizes target names and generates the proper path for you.

> So I guess the question is this -- how should I manage this issue?
> Since EXECUTABLE_OUTPUT_PATH is deprecated, it looks like it has
> functionally been replaced by CMAKE_RUNTIME_OUTPUT_DIRECTORY.  It's
> also subject to the same problem if any CMakeLists.txt file set it
> incorrectly somewhere in a build tree.

AFAIK the word 'deprecated' does not appear in the documentation for
EXECUTABLE_OUTPUT_PATH.  It will be around for a long time.  We just
recommend using the new variables because they are more powerful:

   1.) The new variables actually just initialize target properties
       so the values can be set on a per-target basis.

   2.) The new variables distinguish the .dll and .lib parts of a
       shared library on windows.

Also, the new variables should not be put in the cache by convention.
If you want the user to be able to edit the path, provide a different
cache entry that you use to set the variables.

-Brad