Add macOS Intel/AppleM1 Homebrew migration troubleshooting tips

documentation/docs/dev/troubleshooting.md

-
 # Troubleshooting
 
 ## Packages
@@ -110,3 +109,102 @@ rm /Users/user/Library/Caches/Homebrew/downloads/0cc80cc8d2a1e3066725c5ee623c23c
 ```
 
 and then retry to install.
+
+
+#### Moving from macOS <= 11 (BigSur) to macOS >= 12 (Monterey) on Apple M1 chip
+
+On macOS <= 11, the Homebrew package manager installs everything under `usr/local`. On the contrary, starting from macOS 12 and on machines with the new Apple M1 chip, Homebrew installs all packages under the new, dedicated folder `/opt/homebrew`.
+
+As a result, when migrating your Apple M1 machine from macOS 11 to 12, you might have relics in your `usr/local` folder, which can interfer with the compilation and/or installation of the GeoModel packages.
+
+To be sure to have a clean environment, where Homebrew can install the GeoModel packages without problems, when moving your Apple M1 system to macOS 12 please make sure you don't have any GeoModel relics in `usr/local`. You can check this by running:
+
+```sh
+% ls /usr/local/lib/libGeo*
+```
+
+If you have old GeoModel-related libraries installed, you should see an output like the one below:
+
+```sh
+/usr/local/lib/libGeoGenericFunctions.4.2.6.dylib	/usr/local/lib/libGeoModelDBManager.dylib		/usr/local/lib/libGeoModelWrite.4.2.6.dylib
+/usr/local/lib/libGeoGenericFunctions.4.2.8.dylib	/usr/local/lib/libGeoModelJSONParser.4.2.6.dylib	/usr/local/lib/libGeoModelWrite.4.2.8.dylib
+/usr/local/lib/libGeoGenericFunctions.4.2.9.dylib	/usr/local/lib/libGeoModelJSONParser.4.2.8.dylib	/usr/local/lib/libGeoModelWrite.4.2.9.dylib
+/usr/local/lib/libGeoGenericFunctions.4.dylib		/usr/local/lib/libGeoModelJSONParser.4.dylib		/usr/local/lib/libGeoModelWrite.4.dylib
+/usr/local/lib/libGeoGenericFunctions.dylib		/usr/local/lib/libGeoModelJSONParser.dylib		/usr/local/lib/libGeoModelWrite.dylib
+/usr/local/lib/libGeoMaterial2G4.4.2.6.dylib		/usr/local/lib/libGeoModelKernel.4.2.6.dylib		/usr/local/lib/libGeoModelXMLParser.4.2.6.dylib
+/usr/local/lib/libGeoMaterial2G4.4.dylib		/usr/local/lib/libGeoModelKernel.4.2.8.dylib		/usr/local/lib/libGeoModelXMLParser.4.2.8.dylib
+/usr/local/lib/libGeoMaterial2G4.dylib			/usr/local/lib/libGeoModelKernel.4.2.9.dylib		/usr/local/lib/libGeoModelXMLParser.4.dylib
+/usr/local/lib/libGeoModel2G4.4.2.6.dylib		/usr/local/lib/libGeoModelKernel.4.dylib		/usr/local/lib/libGeoModelXMLParser.dylib
+/usr/local/lib/libGeoModel2G4.4.dylib			/usr/local/lib/libGeoModelKernel.dylib			/usr/local/lib/libGeoModelXml.4.2.6.dylib
+/usr/local/lib/libGeoModel2G4.dylib			/usr/local/lib/libGeoModelRead.4.2.6.dylib		/usr/local/lib/libGeoModelXml.4.2.8.dylib
+/usr/local/lib/libGeoModelDBManager.4.2.6.dylib		/usr/local/lib/libGeoModelRead.4.2.8.dylib		/usr/local/lib/libGeoModelXml.4.dylib
+/usr/local/lib/libGeoModelDBManager.4.2.8.dylib		/usr/local/lib/libGeoModelRead.4.2.9.dylib		/usr/local/lib/libGeoModelXml.dylib
+/usr/local/lib/libGeoModelDBManager.4.2.9.dylib		/usr/local/lib/libGeoModelRead.4.dylib
+/usr/local/lib/libGeoModelDBManager.4.dylib		/usr/local/lib/libGeoModelRead.dylib
+```
+
+and:
+
+```sh
+$> ls /usr/local/lib/libGM*
+/usr/local/lib/libGMXPlugin.4.2.6.dylib	/usr/local/lib/libGMXPlugin.4.2.8.dylib	/usr/local/lib/libGMXPlugin.4.dylib	/usr/local/lib/libGMXPlugin.dylib
+```
+
+and:
+
+```sh
+$> ls /usr/local/lib/libGX*
+/usr/local/lib/libGXBase.4.2.9.dylib			/usr/local/lib/libGXGeometrySystems.4.2.9.dylib		/usr/local/lib/libGXGuideLineSystems.4.2.9.dylib
+/usr/local/lib/libGXBase.4.dylib			/usr/local/lib/libGXGeometrySystems.4.dylib		/usr/local/lib/libGXGuideLineSystems.4.dylib
+/usr/local/lib/libGXBase.dylib				/usr/local/lib/libGXGeometrySystems.dylib		/usr/local/lib/libGXGuideLineSystems.dylib
+/usr/local/lib/libGXClashPointSystems.4.2.9.dylib	/usr/local/lib/libGXGui.4.2.9.dylib			/usr/local/lib/libGXHEPVis.4.2.9.dylib
+/usr/local/lib/libGXClashPointSystems.4.dylib		/usr/local/lib/libGXGui.4.dylib				/usr/local/lib/libGXHEPVis.4.dylib
+/usr/local/lib/libGXClashPointSystems.dylib		/usr/local/lib/libGXGui.dylib				/usr/local/lib/libGXHEPVis.dylib
+```
+
+You can check also the `/usr/local/bin` folder as well, for relics of GeoModel executables:
+
+```sh
+$> ls /usr/local/bin/gm*    
+/usr/local/bin/gmcat		/usr/local/bin/gmex		/usr/local/bin/gmstatistics
+$> ls /usr/local/bin/full*. # for fullSimLight    
+```
+
+Therefore, before installing or compiling GeoModel or GeoModel-dependent packages, clean the `usr/local` folder, first.
+
+To clean it, you can run, for example:
+
+**WARNING:** Before running the commands below, which are provided as examples only, please double check that the `*` does not pick up other, valuable, non-GeoModel libraries you might have installed in `/usr/local`!!!
+
+**NOTE:** Depending on your installation, you might need to run the commands below as `sudo` (as in the examples) or not.
+
+```sh
+sudo rm -f /usr/local/lib/libGeo*
+sudo rm -f /usr/local/lib/libGM*
+sudo rm -f /usr/local/lib/libGX*
+sudo rm -rf /usr/local/lib/libTFPersistification.*
+sudo rm -rf /usr/local/lib/libExpressionEvaluator.*
+sudo rm -rf /usr/local/lib/libGDMLtoGM.*
+sudo rm -rf /usr/local/lib/gxplugins
+sudo rm -rf /usr/local/lib/cmake/GeoModel*
+sudo rm -rf /usr/local/lib/Geant4-11.0.1
+sudo rm -rf /usr/local/lib/libG4*
+
+sudo rm -f /usr/local/bin/gm*
+sudo rm -f /usr/local/bin/gdml2gm
+sudo rm -f /usr/local/bin/fullSimLight 
+sudo rm -f /usr/local/bin/geant4*
+
+sudo rm -rf /usr/local/share/GeoModelXml/
+sudo rm -rf /usr/local/share/gmex
+sudo rm -rf /usr/local/share/Geant4-11.0.1
+
+sudo rm -rf /usr/local/include/ExpressionEvaluator*
+sudo rm -rf /usr/local/include/Geo*
+sudo rm -rf /usr/local/include/GDMLInterface
+sudo rm -rf /usr/local/include/GXClashPointSystems/
+sudo rm -rf /usr/local/include/TFPersistification/
+sudo rm -rf /usr/local/include/VP1*
+sudo rm -rf /usr/local/include/Geant4 
+
+```