possible bug / issue with formula cookbook documentation

[ipatch]

brew config output

NA

brew doctor output

NA

Verification

• [X] I ran brew update and am still able to reproduce my issue.
• [X] I have resolved all warnings from brew doctor and that did not fix my problem.

What were you trying to do (and why)?

i was reading through the formula cookbook documentation and came across

https://github.com/Homebrew/brew/blob/master/docs/Formula-Cookbook.md

and specifically the below line,

https://github.com/Homebrew/brew/blob/68e895ad4d374b4a0022613a20bd046d6487dfd9/docs/Formula-Cookbook.md?plain=1#L713

where it states the prefix references the /usr/local/Cellar/foo/0.1

but in my test case i found when editing a formula see below using .prefix was referencing $(brew --prefix)/opt and not Cellar. not sure if this is suppose to the intended behavior or if .prefix is suppose to reference the Cellar and the documentation or source code needs to be updated to reflect the current path.

https://github.com/ipatch/homebrew-freecad/blob/1575ba8ad4e7d4a4ac95292ea5d90a5949edba32/Formula/freecad.rb#L82

What happened (include all command output)?

running the below command

brew install freecad -v -s

the path to the #{hbp}/opt dir instead of the Cellar dir is being used. not sure if using/calling .prefix is suppose to reference the Cellar or opt dir ?

What did you expect to happen?

i though calling .prefix would point the Cellar and not the opt dir according to the documentation.

Step-by-step reproduction instructions (by running brew commands)

brew tap freecad/freecad;
echo "semicolons cause i care about copypasta";
echo "i use fish";
cd (brew --repository freecad/freecad);
git remote add ipatch https://github.com/ipatch/homebrew-freecad;
git fetch ipatch;
git checkout freecad.update.to.0.20.release ;
brew install freecad/freecad/freecad;

then look at the output for the cmake_prefix_path

[Bo98]

Basically the prefix to the formula being installed will point to the Cellar, but accessing the prefix of other formualae will point to the opt path. This is because Cellar paths are not stable and shouldn't really be referenced in other formulae as you risk, if that path ends up being baked somewhere in the resulting install, having to revision bump every time that other formula has a version/revision change, regardless if anything meaningful actually changed.

Pointing to the opt path should never be an issue in practice. Why do you need the Cellar path?

[ipatch]

forgive if i'm missing something here, when i run brew install freecad (after running the previous steps, of course) i see the below output when install process errors / completes

==> ENV
HOMEBREW_CC: clang
HOMEBREW_CXX: clang++
MAKEFLAGS: -j8
CMAKE_PREFIX_PATH: /Users/chris/homebrew/opt/icu4c:/Users/chris/homebrew/opt/[email protected]:/Users/chris/homebrew/opt/readline:/Users/chris/homebrew/opt/sqlite:/Users/chris/homebrew/opt/[email protected]:/Users/chris/homebrew/opt/boost-python3.10:/Users/chris/homebrew/opt/llvm:/Users/chris/homebrew/opt/libffi:/Users/chris/homebrew/opt/jpeg-turbo:/Users/chris/homebrew/opt/qt@5::/Users/chris/homebrew/opt/cython:/Users/chris/homebrew/opt/tcl-tk:/Users/chris/homebrew/opt/openblas:/Users/chris/homebrew/opt/[email protected]:/Users/chris/homebrew/opt/sphinx-doc:/Users/chris/homebrew/opt/[email protected]:/Users/chris/homebrew

that's just a snippet but the cmake_prefix path is using the opt dir but when i editing the formula to use the .prefix in the initial setup command the .prefix points to the Cellar dir as seen below,

==> cmake -DCMAKE_INSTALL_PREFIX=/Users/chris/homebrew/Cellar/freecad/0.20 -DCMAKE_INSTALL_LIBDIR=lib -DCMAKE_BUILD_TYPE=Release -DCMAKE_FIND_FRAMEWORK=LAST -DCMAKE_VERBOSE_MAKEFILE=ON -Wno-dev -DBUILD_TESTING=OFF -DCMAKE_OSX_SYSROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX12.sdk -DHOMEBREW_PREFIX=/Users/chris/homebrew -DPYTHON_EXECUTABLE=/Users/chris/homebrew/bin/python3 -DPYTHON_INCLUDE_DIR=/Users/chris/homebrew/opt/[email protected]/Frameworks/Python.framework/Headers -DPYTHON_LIBRARY=/Users/chris/homebrew/opt/[email protected]/Frameworks/Python.framework/Versions/Current/lib/libpython3.10.dylib -DBUILD_SMESH=1 -DBUILD_QT5=1 -DFREECAD_USE_EXTERNAL_KDL=1 -DBUILD_FEM_NETGEN=0 -DBUILD_ENABLE_CXX_STD=C++17 -DCMAKE_PREFIX_PATH="/Users/chris/homebrew/opt/xerces-c;/Users/chris/homebrew/opt/opencascade;/Users/chris/homebrew/opt/hdf5;/Users/chris/homebrew/opt/coin3d;/Users/chris/homebrew/opt/qt@5;/Users/chris/homebrew/opt/vtk;/Users/chris/homebrew/opt/[email protected]/lib/cmake/PySide2-5.15.5;/Users/chris/homebrew/opt/med-file;/Users/chris/homebrew/Cellar/boost-python3.10/1.79.0;" -DFREECAD_CREATE_MAC_APP=1 ..

---

this something i noticed while troubleshooting a larger issue at hand. so i guess the documentation is correct in that using .prefix or calling .prefix on object (if that's how one says it 🤔) but it looks like the code (source the internal brew commands) could be mutating my input and using the opt dir instead of the Cellar

[gromgit]

CMAKE_INSTALL_PREFIX is automatically set to the versioned Cellar directory because cmake needs to know where to physically put the files. The opt prefix is a symlink to the currently-installed version, that will point to .../Cellar/freecad/0.20 today, but .../Cellar/freecad/0.21 in the future.

[carlocab]

Calling Formula["foo"].prefix from inside Formula["bar"] will return an opt path. Calling Formula["foo"].prefix from inside Formula["foo"].prefix will return a Cellar path.

This is by design. Cellar paths are implementation details that are internal to brew -- you don't want to show these unnecessarily to the build.

[ipatch]

Calling Formula["foo"].prefix from inside Formula["bar"] will return an opt path. Calling Formula["foo"].prefix from inside Formula["foo"].prefix will return a Cellar path.

This is by design. Cellar paths are implementation details that are internal to brew -- you don't want to show these unnecessarily to the build.

that definitely seems like a gotcha, and should be documented or at least brought to the attention of the reader in the formula cookbook. or maybe, i just over looked it, and thanks for the explanation.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs.