BUILD_macos.md

MacOS Environment Setup

To set up your MacOS environment, follow these steps using Homebrew as the main package manager. Aim to install versions specified in build.assets/versions.mk; for others, use the latest Homebrew version.

The instructions below are provided on a best-effort basis. PRs with corrections and updates are welcome!

1. Install Homebrew

2. Install Go

   brew install go

3. Install Rust

   1. Install rustup

      Install rustup with Homebrew:

      brew install rustup
      
      rustup-init
      # Accept defaults

   2. Install and configure Rust toolchain

      1. Find the required Rust version in build.assets/versions.mk (RUST_VERSION).

      2. Install the Rust toolchain:

         # Replace <version> with the value of RUST_VERSION from build.assets/versions.mk (e.g., 1.81.0)
         rustup toolchain install <version>

      3. Set the default Rust toolchain globally (applies to all projects):

         # Replace <version> with the value of RUST_VERSION from build.assets/versions.mk (e.g., 1.81.0)
         rustup default <version>

         Note: Using rustup default <version> sets the toolchain globally for your user. If you only want to override the toolchain for a specific project directory, use rustup override set <version> inside that directory instead.

      4. Verify the installed version:

         rustc --version

4. Install Node.js

   1. Find the required Node version in build.assets/versions.mk (NODE_VERSION).

   2. Install Node.js (Homebrew only supports MAJOR version):

      # Replace <version> with the MAJOR value of NODE_VERSION from build.assets/versions.mk (e.g., 22)
      brew install node@<version>

   3. Install to PATH and apply the changes to your shell:

      # Replace <version> with the MAJOR value of NODE_VERSION from build.assets/versions.mk (e.g., 22)
      echo 'export PATH="/opt/homebrew/opt/node@<version>/bin:$PATH"' >> ~/.zshrc
      
      source ~/.zshrc

   4. Verify the installed version:

      node --version

5. Install wasm-pack:

   1. Find the required wasm-pack version in build.assets/versions.mk (WASM_PACK_VERSION).

   2. Install wasm-pack globally:

      # Replace <version> with the value of WASM_PACK_VERSION from build.assets/versions.mk (e.g., 0.12.1)
      npm install --global wasm-pack@<version>

   3. Verify wasm-pack version:

      wasm-pack --version

6. Install libfido2:

   brew install libfido2

7. Install pkg-config:

   brew install pkg-config

8. Install helm and the helm-unittest plugin:

   brew install helm
   
   helm plugin install https://github.com/quintush/helm-unittest --version 0.2.11

9. Install bats:

   1. Find the required bats-core version from build.assets/Dockerfile (search for bats-core).

   2. Set the version variable and install bats-core:

      # Replace <version> with the required bats-core version (e.g., 1.12.0)
      BATS_VERSION=1.12.0
      
      curl -L https://github.com/bats-core/bats-core/archive/v${BATS_VERSION}.tar.gz -o ~/Downloads/bats.tar.gz
      cd ~/Downloads
      tar xzvf bats.tar.gz
      sudo mkdir -p /usr/local/libexec
      sudo chown $USER /usr/local/libexec
      cd bats-core-${BATS_VERSION}
      sudo ./install.sh /usr/local
      cd ../
      rm -rf bats-core-${BATS_VERSION} bats.tar.gz

   3. Verify bats installation:

      bats --version

10. Increase the maximum number of open files:

    ulimit -n 2560 # 10x default

11. Test the environment by building development artifacts and running tests:

    make all test

Congrats! Your MacOS environment is now ready for development 🎉

If you encounter any issues, please refer to the official documentation or open an issue in the repository for assistance.