# Install on macOS

The most convenient way to install COSEDA (and its dependency [CrystFEL](https://www.desy.de/~twhite/crystfel/index.html)) is to use the [Homebrew](https://brew.sh) package manager. The installation is done in 3 simple steps via the command line.

## Installing Homebrew (skip if already using Homebrew)

### 1) Install Xcode Command Line Tools

```bash
xcode-select --install
```

### 2) Install Homebrew

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

### 3) Add Homebrew to you shell

For Apple Silicon Macs

```bash
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
```

For Intel Macs

```bash
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"
```

If you are unsure which one you have click on the Apple logo in the Menu bar -\> About This Mac -\> Chip.

### 4) Check

```bash
brew --version
brew doctor
```

Congrats, this was the hardest part.

## Installing COSEDA

### 1) Add the tap

This tells Homebrew where it can find the source of COSEDA.

```bash
brew tap kristallorakel/coseda https://gitlab.com/kristallorakel/homebrew-coseda.git
```

### 2) Install

```bash
brew install coseda
```

### Optional: install the nightly build

The nightly build contains beta changes from the development branch. It is useful for testing new features, but it may be less stable than the regular release.

```bash
brew install coseda-nightly
```

The stable and nightly formulas both install the `coseda` command and `COSEDA.app`, so Homebrew will not install them side by side. To switch between them:

```bash
brew uninstall coseda
brew install coseda-nightly
```

or:

```bash
brew uninstall coseda-nightly
brew install coseda
```

### 3) Run

If the installation was successful, you can run COSEDA via a simple command. Running it for the first time might take a moment, please be patient.

```bash
coseda
```

### Update

COSEDA checks for updates automatically on startup and will prompt you to upgrade with a single button click.

If you prefer to update manually from the terminal:

```bash
brew upgrade coseda
```

### Troubleshooting: "Cannot install under Rosetta 2"

If the in-app update fails with a Rosetta 2 error, macOS has incorrectly marked COSEDA to run under x86_64 emulation. To fix it:

1. Right-click `COSEDA.app` in Finder → **Get Info**
2. Uncheck **Open using Rosetta**
3. Relaunch COSEDA — the update button will now work

Alternatively, run the upgrade once from a terminal:

```bash
brew upgrade coseda
```

This is a one-time fix. Newer installations are not affected.

## Installing CrystFEL

[CrystFEL](https://www.desy.de/~twhite/crystfel/index.html) is COSEDA's most important dependency. Similarly, you can install it using homebrew:

```bash
brew tap desy/crystfel https://gitlab.desy.de/thomas.white/homebrew-crystfel
brew install crystfel
```