.. _macos_installation: MacOS installation ============ Step by step guide ------------------ 0. Installation should take less than 1 h. Most time will be spent compiling `R` and `python` packages where binaries are not available. `DISCLAIMER`: While we aimed to make this installation process as simple as possible, a basic knowledge of `running commands in Terminal `_ and `installing packages R `_ is helpful. 1. Install library dependencies. We recommend using `Homebrew `_ to install the necessary dependencies. If you do not have Homebrew, install it by typing or pasting the following into `Terminal`: .. code-block:: bash :caption: Install Homebrew /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" You need to add Homebrew to your `PATH` variable to make it available (`see here why `_). .. code-block:: bash :caption: Add Homebrew to your PATH echo 'eval $(/opt/homebrew/bin/brew shellenv)' >> ~/.zprofile eval $(/opt/homebrew/bin/brew shellenv) .. attention:: If you are running on `Apple Silicon` (Mx) make sure that Homebrew is recognising the correct machine architecture. In `Terminal` run `brew config`. The output should look something like the following. The important information is that `macOS` should be `arm64`, `Rosetta 2` should be `false` and `HOMEBREW_PREFIX` should be ``/opt/homebrew``. .. code-block:: bash :caption: Expected output of `brew config` HOMEBREW_VERSION: 4.4.5 ORIGIN: https://github.com/Homebrew/brew HEAD: 254bf3fe9d8fa2e1b2fb55dbcf535b2d870180c4 Last commit: 8 days ago Core tap JSON: 18 Nov 05:40 UTC Core cask tap JSON: 18 Nov 05:40 UTC HOMEBREW_PREFIX: /opt/homebrew HOMEBREW_CASK_OPTS: [] HOMEBREW_MAKE_JOBS: 24 Homebrew Ruby: 3.3.6 => /opt/homebrew/Library/Homebrew/vendor/portable-ruby/3.3.6/bin/ruby CPU: 24-core 64-bit arm_blizzard_avalanche Clang: 16.0.0 build 1600 Git: 2.39.5 => /Applications/Xcode.app/Contents/Developer/usr/bin/git Curl: 8.7.1 => /usr/bin/curl macOS: 15.1-arm64 CLT: 16.1.0.0.1.1729049160 Xcode: 16.1 Rosetta 2: false If `HOMEBREW_PREFIX` is ``/usr/local`` and the other parameters also do not match, you might have to check that `Terminal` is running in the correct mode. Do the following is based on this `Stackoverflow post `_. Go to: `Finder` -> `Applications` -> `Utilities` -> `Terminal`. Right click on Terminal and select `Get Info`. Uncheck checkbox: 'Open using Rosetta'. Quit Terminal Application. Restart Terminal and check your machine arhictecture: .. code-block:: bash :caption: Check machine architecture uname -m # should return arm64 NOT x86_64 Then, `remove Homebrew `_ and `install `_ again. Then install the required programs using Homebrew via `Terminal`: .. code-block:: bash :caption: Install required programs via Homebrew brew install pstree openssl gdal cmake 2. You will also most likely need `Xcode `_ to compile packages in `R` and `Python`. Follow the installation instructions on `Mac App Store `_. 3. Install `R base for MacOS `_ and `RStudio `_. We tested this on R version `4.4.1`. If you use an older version of `R` the package dependencies might not be resolved during ``renv::init``. .. attention:: While we recomment `RStudio` for analysis, we recommend using `Terminal` for the installation process. Open `Terminal`, type in `R` and follow the same instructions. We encountered several issues that header files could not be found when using `RStudio` and `renv`, such as, ``fatal error: 'cstlib' file not found`` or ``fatal error: 'iostream' file not found``. It might be that `RStudio` is modifying the `PATH` variable when using `renv`, see `Github issue `_. 4. Use `Terminal` (or `RStudio`) and install `renv` in the `R` console. .. code-block:: R :caption: Install renv install.packages("renv") 5. Install package dependencies. * Create a folder under `Applications` named `cecelia`. * Within the `cecelia` folder create a directory `projects` where all projects data will be stored. * Download the `renv.lock file `_ into ``/Applications/cecelia``. `Important`: save this as renv.lock NOT renv.lock.txt. Remove `.txt` if this is appended during the download. * Then in `R`, create the R-environment using the example below. To do this, you must set the current working directory to the directory where the renv.lock file is located. * When prompted during the process, Select `1` to restore the project from the lockfile. * `YOU NEED AT LEAST R version 4.4.1 OTHERWISE THIS WILL FAIL.` * `THIS STEP WILL INSTALL ALL REQUIRED R PACKAGES. THERE IS NO NEED TO MANUALLY INSTALL PACKAGES. IF YOU ARE MISSING PACKAGES WHEN STARTING THE APP, THEN YOU NEED TO COME BACK TO THIS STEP.` .. tip:: We are going to use the path ``/Applications/cecelia`` throughout this manual. You can place it anywhere else if you want. .. tip:: `Unix` systems have three main signs to specify directories .. code-block:: bash :caption: Common path directories ~ defines the home directory . defines the current directory .. defines the parent directory ~/Documents is shortform for /Users/dom/Documents .. code-block:: R :caption: Init R-environment # An example would be setwd("/Applications/cecelia") renv::init() .. attention:: Make sure that this command installs ALL required packages, that is, there should be a long list of packages including some from Github and Bioconductor. If that is not the case, check that the `lock-file` has packages listed, download the file again if needed, and repeat the previous step with ``renv::init()``. We had cases where the `lock-file` was reset and not all packages installed. .. attention:: If you run into issues that `R` cannot compile a package with `gfortran`, such as `make: /opt/gfortran/bin/gfortran: No such file or directory`, it might be that the path cannot be found because `gfortran` is now packaged into `gcc` and `R` might be looking in the wrong spot. To change this location follow the instructions as outlined in this `Stackoverflow post `_. In `Terminal` install `gcc`: .. code-block:: bash :caption: Install gcc brew install gcc Check your `gcc` version with: .. code-block:: bash :caption: Check gcc version ls /opt/homebrew/Cellar/gcc/ # for Apple Silicon ls /usr/local/Cellar/gcc/ # for macOS Intel Create a file `~/.R/Makevars` and enter the following. You need to change the `gcc` version for your version number. .. code-block:: bash :caption: Change Fortran paths FC = /opt/homebrew/Cellar/gcc/11.3.0_2/bin/gfortran F77 = /opt/homebrew/Cellar/gcc/11.3.0_2/bin/gfortran FLIBS = -L/opt/homebrew/Cellar/gcc/11.3.0_2/lib/gcc/11 .. attention:: If you still run into compiler issues, please remove and re-install `Xcode `_. .. code-block:: bash :caption: Reinstall Xcode sudo rm -fr /Library/Developer/CommandLineTools xcode-select --install .. image:: _images/macos_install_renv.png :width: 100% 6. Load the environment you have just created and install `Cecelia` package. .. code-block:: R :caption: Install Cecelia package renv::load() renv::install("schienstockd/cecelia") .. image:: _images/macos_ccia_install.png :width: 100% 7. You must define a `base directory` where configuration files, models and the `shiny app` will be stored. .. code-block:: R :caption: Define base directory library(cecelia) cciaSetup("/Applications/cecelia") In case you get stuck at any point and have to restart R, you need to redefine the path you are working on .. code-block:: R :caption: Restart Cecelia Sys.setenv(KMP_DUPLICATE_LIB_OK = "TRUE") renv::load("/Applications/cecelia") library(cecelia) cciaUse("/Applications/cecelia") .. image:: _images/macos_ccia_setup.png :width: 100% 8. `Cecelia` depends on a `conda environment` which must be created. .. code-block:: R :caption: Install miniconda reticulate::install_miniconda() .. attention:: If you get a `timeout` error you might have to adjust the limit in R. .. code-block:: R :caption: Adjust time limit options(timeout=600) .. image:: _images/macos_miniconda_install.png :width: 100% 9. For Apple Silicon systems (Mx), you `must` pre-create the conda environment in `Terminal` otherwise it will use the wrong platform type. You must source `conda` first with the following commands. `reticulate::miniconda_path()` will give you the conda path that you must put into the following command. .. code-block:: bash :caption: Pre-create conda environment in `Terminal` . /REPLACE_ME/etc/profile.d/conda.sh CONDA_SUBDIR=osx-arm64 conda create -n r-cecelia-env python=3.12 .. image:: _images/macos_arm_conda_create.png :width: 100% 10. Then, back in Rstudio, Create conda environment¶ .. code-block:: R :caption: Create conda environment cciaCondaCreate() .. attention:: If you get a compiler error such as ``fatal error: 'map' file not found`` you might have to reinstall Xcode as stated above during ``renv::init``. .. code-block:: bash :caption: Reinstall Xcode sudo rm -fr /Library/Developer/CommandLineTools xcode-select --install .. image:: _images/macos_conda_create.png :width: 100% 11. Download models for deep-learning segmentation, tracking and others. .. code-block:: R :caption: Download models cciaModels() .. image:: _images/macos_ccia_models.png :width: 100% 12. Create `shiny app` in `base directory`. .. code-block:: R :caption: Create `shiny app` cciaCreateApp() .. image:: _images/macos_create_app.png :width: 100% 13. Adjust the config file. If you want to adjust where your projects are located, you must adjust the parameters in ``/Applications/cecelia/custom.yml`` to your system and download `bioformats2raw`: * Download `bioformats2raw `_ and place it into the ``/Applications`` folder .. code-block:: YAML :caption: Adjust config in text editor of RStudio default: dirs: bioformats2raw: "/Applications/bioformats2raw-0.9.0/" projects: "/Applications/cecelia/projects" volumes: home: "~/" computer: "/" python: conda: env: "r-cecelia-env" source: env: "r-cecelia-env" .. image:: _images/macos_custom_config.png :width: 100% 14. Run the `app`. To start the application, double click `cecelia-macOSX.command` located in ``/Applications/cecelia/app/``. .. code-block:: bash :caption: Run `Cecelia` app /Applications/cecelia/app/cecelia-macOSX.command .. image:: _images/macos_run_app.png :width: 100%