doc: update building instructions for macos

[joneugster]

• Add instruction for building on macOS
• Fix: minimum cmake version below 3.5 leads to error with cmake 4+
• Update stale link for clipper library

[joneugster]

I understood this as

mkdir ./src/build
cd ./src/build
cmake ..

but it looks like what's meant is

mkdir ./build
cd ./build
cmake ..

isn't it?

[dg0yt]

I don't see a significant difference between "source directory" and "project's root directory".

• The first term is actually found in CMake (CMAKE_SOURCE_DIR, CMAKE_CURRENT_SOURCE_DIR. I admit there is also PROJECT_SOURCE_DIR and <ProjectName>_SOURCE_DIR.)
• OTOH "root" can refer to installed trees in CMake.

[joneugster]

ok, I've dropped that change.

[dg0yt]

Thanks for your suggestions. I did a cursory review now.

FTR future updates might consider ninja instead of make, and driving build steps via cmake --build <target>.

[dg0yt]

I don't see a significant difference between "source directory" and "project's root directory".

• The first term is actually found in CMake (CMAKE_SOURCE_DIR, CMAKE_CURRENT_SOURCE_DIR. I admit there is also PROJECT_SOURCE_DIR and <ProjectName>_SOURCE_DIR.)
• OTOH "root" can refer to installed trees in CMake.

[dg0yt]

Is there an error with CMake 4.x?

[joneugster]

The error I'm seeing is

-- Could NOT find Polyclipping (missing: POLYCLIPPING_INCLUDE_DIR POLYCLIPPING_LIBRARY) (Required is at least version "6.1.3")
CMake Warning at CMakeLists.txt:182 (message):
  System polyclipping is missing.  Enabling embedded build.

  Set Mapper_BUILD_CLIPPER=OFF to disable embedded build.


CMake Error at 3rd-party/clipper/CMakeLists.txt:22 (cmake_minimum_required):
  Compatibility with CMake < 3.5 has been removed from CMake.

  Update the VERSION argument <min> value.  Or, use the <min>...<max> syntax
  to tell CMake that the project requires at least <min> but has been updated
  to work with policies introduced by <max> or earlier.

  Or, add -DCMAKE_POLICY_VERSION_MINIMUM=3.5 to try configuring anyway.


-- Configuring incomplete, errors occurred!

actually I think I do get it to work by adding -DCMAKE_POLICY_VERSION_MINIMUM=3.7 as suggested

[joneugster]

I've now updated the one instance of cmake_minimum_required which was causing the error. I'm oblivious about any implications this might or might not have.

Actually, there's a few build warnings about path normalisations which would dissappear by requiring cmake_minimum_required(3.31.0) but I deemed it too bold to propose that now in this PR. Besides, there would be other options to address these comments, besides bumping required deps.

[dg0yt]

I see. I use some input variable to close the gap, but this need to eventually land in CMakeLists.txt. Then we don't need it in instructions.

[dg0yt]

Not sure if this useful for the intended audience. (At least it is not specific for brew.)
Otherweise we might also need to mention make install and make package.

[joneugster]

I might not be part of the target audience myself :) but I personally would appreciate anything mentioning these things.

[joneugster]

I've removed the sentence now since you seem not to be thrilled about it :)