Skip to content

Commit f5a4eb8

Browse files
EmoSaruclaude
EmoSaru
and
claude
committed
Warn that running outside /Applications breaks auto-updates on macOS
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 1e17011 commit f5a4eb8

1 file changed

Lines changed: 143 additions & 0 deletions

File tree

‎docs/Installation.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Installing EmoTracker
2+
3+
EmoTracker is available for Windows, macOS, and Linux. Download the latest release from the
4+
[Releases page](https://github.com/EmoTracker-Community/EmoTracker/releases) and follow the
5+
instructions for your platform below.
6+
7+
---
8+
9+
## Windows
10+
11+
### 1. Download
12+
13+
From the Releases page, download **`EmoTracker-VERSION-win-x64.zip`**.
14+
15+
### 2. Choose an install location
16+
17+
Extract the zip to a permanent folder of your choice — for example `C:\EmoTracker` or
18+
`C:\Games\EmoTracker`. EmoTracker runs directly from this folder; there is no traditional installer.
19+
20+
> **Warning: Avoid Windows-protected folders (Controlled Folder Access)**
21+
>
22+
> If Windows Defender's **Controlled Folder Access (CFA)** feature is enabled on your system,
23+
> placing EmoTracker inside any of the following default protected folders will prevent the
24+
> built-in auto-updater from working:
25+
>
26+
> - Desktop
27+
> - Documents (My Documents)
28+
> - Pictures
29+
> - Videos
30+
> - Music
31+
>
32+
> EmoTracker will detect this situation and abort the update with a warning rather than fail
33+
> silently. To avoid the issue entirely, install EmoTracker somewhere outside these folders,
34+
> such as `C:\EmoTracker` or a subfolder of `C:\Games`.
35+
>
36+
> If you must keep EmoTracker inside a protected folder, you can whitelist `EmoTracker.exe` in
37+
> **Windows Security → Virus & threat protection → Ransomware protection →
38+
> Allow an app through Controlled Folder Access**.
39+
40+
### 3. Run
41+
42+
Open the extracted folder and double-click **`EmoTracker.exe`**.
43+
44+
---
45+
46+
## macOS
47+
48+
### 1. Download
49+
50+
From the Releases page, download **`EmoTracker-VERSION-osx-universal.tar.gz`**.
51+
52+
This is a universal binary that runs natively on both Apple Silicon (arm64) and Intel (x64) Macs.
53+
macOS 10.15 Catalina or later is required.
54+
55+
### 2. Extract
56+
57+
Double-click the `.tar.gz` file in Finder, or run the following in Terminal:
58+
59+
```sh
60+
tar xf EmoTracker-VERSION-osx-universal.tar.gz
61+
```
62+
63+
This produces `EmoTracker.app`.
64+
65+
### 3. Move to Applications
66+
67+
Drag `EmoTracker.app` into your `/Applications` folder.
68+
69+
> **Warning: Running from outside `/Applications` will break auto-updates**
70+
>
71+
> macOS applies **App Translocation** to apps that are run directly from a download location
72+
> (e.g. your Downloads folder or an unextracted archive). When translocation is active, macOS
73+
> runs the app from a hidden read-only path, which prevents the built-in auto-updater from
74+
> replacing the app bundle. EmoTracker will detect this and abort the update with a warning
75+
> rather than fail silently.
76+
>
77+
> Moving `EmoTracker.app` to `/Applications` (or any other permanent folder outside your
78+
> Downloads directory) clears the translocation flag and allows updates to work correctly.
79+
80+
### 4. First launch — Gatekeeper
81+
82+
Because EmoTracker is distributed outside the Mac App Store, macOS will block it on the first
83+
launch. To open it:
84+
85+
1. **Right-click** (or Control-click) `EmoTracker.app` and choose **Open**.
86+
2. Click **Open** in the dialog that appears.
87+
88+
You only need to do this once. Subsequent launches work normally.
89+
90+
Alternatively, if you already double-clicked and got a "cannot be opened" message:
91+
92+
1. Open **System Settings → Privacy & Security**.
93+
2. Scroll down to the Security section and click **Open Anyway** next to the EmoTracker entry.
94+
95+
> **Note:** The built-in auto-updater automatically removes the quarantine attribute from
96+
> downloaded updates, so you will not need to repeat this process after each update.
97+
98+
### 5. Run
99+
100+
Double-click `EmoTracker.app` in Finder, or open it from Launchpad.
101+
102+
---
103+
104+
## Linux
105+
106+
### 1. Download
107+
108+
From the Releases page, download **`EmoTracker-VERSION-linux-x64.zip`**.
109+
110+
### 2. Extract
111+
112+
```sh
113+
unzip EmoTracker-VERSION-linux-x64.zip -d EmoTracker
114+
```
115+
116+
This creates an `EmoTracker` directory containing the application files.
117+
118+
### 3. Make the binary executable
119+
120+
```sh
121+
chmod +x EmoTracker/EmoTracker
122+
```
123+
124+
### 4. Run
125+
126+
```sh
127+
./EmoTracker/EmoTracker
128+
```
129+
130+
You can also create a desktop shortcut or launcher entry pointing to the `EmoTracker` binary.
131+
132+
> **Note:** The release includes a self-contained .NET 8 runtime, so no separate .NET
133+
> installation is required. Audio playback uses the system audio libraries — make sure your
134+
> distribution has ALSA or PulseAudio/PipeWire available (this is standard on most desktop
135+
> distributions).
136+
137+
---
138+
139+
## Updating
140+
141+
EmoTracker includes a built-in auto-updater. When a new release is available you will be
142+
prompted inside the application. Accepting the update downloads, installs, and relaunches
143+
EmoTracker automatically. No manual download is required for subsequent updates.

0 commit comments

Comments
 (0)