cmake instructions in README are not correct

[Apreche]

I'm not familiar with cmake, but the instructions in the README were not working for me. I could not get it to put the build files into a build directory. I tried to create a build directory, and it complained that the CMakeLists.txt was not located in that build directory. Moving the file into that directory didn't work. In the end, I was only able to make it work just by building in the projects top level directory like so:

cmake -DCMAKE_BUILD_TYPE=Release && make

When I checked the man page for my version of cmake, there was no mention whatsoever of the -B parameter. I have cmake version 3.10.2 on Ubuntu 18.04.

Here is some terminal output of me trying to make it work that is probably a better illustration of the problem.

apreche:~/projects/tvision [master] $ ls
CMakeLists.txt  COPYRIGHT  examples  hello.cpp  include  project  README.md  source
apreche:~/projects/tvision [master] $ cmake . -B ./build -DCMAKE_BUILD_TYPE=Release && cmake --build ./build
CMake Error: The source directory "/home/apreche/projects/tvision/build" does not exist.
Specify --help for usage, or press the help button on the CMake GUI.
apreche:~/projects/tvision [master] $ mkdir build
apreche:~/projects/tvision [master] $ cmake . -B ./build -DCMAKE_BUILD_TYPE=Release && cmake --build ./build
CMake Error: The source directory "/home/apreche/projects/tvision/build" does not appear to contain CMakeLists.txt.
Specify --help for usage, or press the help button on the CMake GUI.
apreche:~/projects/tvision [master] $ cp CMakeLists.txt build/
apreche:~/projects/tvision [master] $ cmake . -B ./build -DCMAKE_BUILD_TYPE=Release && cmake --build ./build
-- The C compiler identification is GNU 7.5.0
-- The CXX compiler identification is GNU 7.5.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Performing Test SUPPORTS_COUNTER_MACRO
-- Performing Test SUPPORTS_COUNTER_MACRO - Success
-- Install path: /usr/local
-- Build Examples: ON
-- Build w/GPM: ON
You have called ADD_LIBRARY for library tvision without any source files. This typically indicates a problem with your CMakeLists.txt file
-- gpm library requested
-- gpm library found
CMake Error at CMakeLists.txt:202 (add_subdirectory):
  add_subdirectory given source "examples" which is not an existing
  directory.

-- Configuring incomplete, errors occurred!
See also "/home/apreche/projects/tvision/CMakeFiles/CMakeOutput.log".
apreche:~/projects/tvision [master] $ ls
build  CMakeCache.txt  CMakeFiles  CMakeLists.txt  COPYRIGHT  examples  hello.cpp  include  project  README.md  source
apreche:~/projects/tvision [master] $ ls build/
CMakeLists.txt
apreche:~/projects/tvision [master] $

vs

apreche:~/projects/tvision [master] $ cmake -DCMAKE_BUILD_TYPE=Release && make
-- The C compiler identification is GNU 7.5.0
-- The CXX compiler identification is GNU 7.5.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features

...

[ 98%] Building CXX object examples/mmenu/CMakeFiles/mmenu.dir/test.cpp.o
[ 99%] Linking CXX executable ../../mmenu
[ 99%] Built target mmenu
Scanning dependencies of target palette
[ 99%] Building CXX object examples/palette/CMakeFiles/palette.dir/palette.cpp.o
[100%] Building CXX object examples/palette/CMakeFiles/palette.dir/test.cpp.o
[100%] Linking CXX executable ../../palette
[100%] Built target palette
apreche:~/projects/tvision [master %] $ ls
build           CMakeFiles           CMakeLists.txt  examples  genphone  hello.cpp  libtvision.a  mmenu    parts.f32     project    source  tvdir   tvforms
CMakeCache.txt  cmake_install.cmake  COPYRIGHT       genparts  hello     include    Makefile      palette  phonenum.f32  README.md  tvdemo  tvedit  tvhc
apreche:~/projects/tvision [master %] $

[magiblot]

Hi, Scott!

I'm sorry for the inconvenience. From time to time I test the build steps using older CMake versions but unfortunately I hadn't ran across this issue.

Here is a short explanation of how CMake works:

The first argument of the cmake command should be a directory with a CMakeLists.txt file in it. CMake will then generate temporary files such as CMakeCache.txt and Makefile; they are created in the current directory by default, as shown in your second code snippet. -B should in theory override this output directory, but unfortunately it didn't work for you.

Another way of doing this would be:

mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release # Upper directory contains 'CMakeLists.txt'.
cmake --build . # Equivalent to 'make' in your case.

If you find the build directory superfluous, what you did is already okay.

I will try to make the build instructions clearer so that nobody else faces the same issue in the future.

Thanks!

[Apreche]

Wow, thanks for the prompt and very helpful response. This worked perfectly. Excited to make some little apps with this. Thanks!

[magiblot]

Cool! Don't hesitate to open an issue or discussion if you have any doubts.

Cheers!