diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 00000000..53201a4e --- /dev/null +++ b/.editorconfig @@ -0,0 +1,5 @@ +# https://editorconfig.org +root = true + +[*.md] +charset = utf-8 diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index d3a2904d..98bbf117 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -40,4 +40,6 @@ Attach your Libation log file here. If your user folder contains the file "Libat |macOS|`~/Library/Application Support/Libation`| |Linux|`~/.local/share/Libation`| +**macOS:** If that folder does not exist because Libation never starts, try launching from Terminal and say whether it works: `/Applications/Libation.app/Contents/MacOS/Libation` (see [Troubleshooting for macOS](https://github.com/rmcrackan/Libation/blob/main/docs/advanced/troubleshoot.md#macos)). + Alternative, you may open the log file folder from within Libation. Open Libation's settings, and on the first tab in Settings you can click the button 'Open log folder'. diff --git a/docs/advanced/troubleshoot.md b/docs/advanced/troubleshoot.md index f2280d23..086f4acd 100644 --- a/docs/advanced/troubleshoot.md +++ b/docs/advanced/troubleshoot.md @@ -7,22 +7,42 @@ It is located alongside the Libation app (though not included in the docker cont ### Windows -Hangover.exe is located in the folder containing Libation.exe. Double-click it to rune it. +Hangover.exe is located in the folder containing Libation.exe. Double-click it to run it. ### macOS -Hangover is located inside the app bundle. Either: -1. From a terminal, run this command: `open -a Libation.app --args hangover` +**Hangover** is located inside the app bundle. Either: +1. From a terminal, run this command: `open /Applications/Libation.app --args hangover` 2. Run it from within the app bundle. 1. In finder, right-click the Libation app bundle and "Show Package Contents" 2. Open folders "Contents" > "MacOS" - 3. Find the file named "Hangover" and double-click it to run it. + 3. Find the file named "Hangover" and double-click it to run it. + +**App won't start** (for example the Dock icon appears and bounces but no window opens, or **`~/Library/Application Support/Libation` is never created**): macOS may be blocking or mishandling launch of the app bundle. That can happen with strict security settings, quarantine flags on the download, or **unsupported macOS setups** (for example hardware past Apple's support window with tools such as OpenCore Legacy Patcher). Symptoms can include double-clicking Libation doing nothing useful, Activity Monitor showing almost no CPU use, no logs yet, and **`open /Applications/Libation.app --args hangover`** failing with error **-128** (`_LSOpenURLsWithCompletionHandler`). Libation is intended for **Apple-supported macOS releases** in [Install on MacOS](/docs/installation/mac); unofficial upgrades are **not supported**, and the steps below are community-tested workarounds. + +Try the following in order: + +1. **Clear extended attributes (including quarantine)** on the installed app, then try opening Libation again from Applications: + ```bash + xattr -cr /Applications/Libation.app + ``` +2. **Run the main executable from Terminal** (same idea as [Running LibationCli](/docs/installation/mac#running-libationcli), but for the GUI). This bypasses some Launch Services paths and has resolved "won't start" reports where `open` failed (for example with error **-128**): + ```bash + /Applications/Libation.app/Contents/MacOS/Libation + ``` + To capture any output to a file (it may be empty): + ```bash + /Applications/Libation.app/Contents/MacOS/Libation > ~/Desktop/libation_debug.log 2>&1 + ``` +3. If you still need Hangover and **`open /Applications/Libation.app --args hangover` fails**, run **Hangover** from the bundle using Finder (see option 2 under **Hangover** above). +4. Confirm you installed the **correct architecture** ([Install on MacOS](/docs/installation/mac)): **arm64** for Apple Silicon, **x64** for Intel. +5. **Crash logs**: open **Console** (Applications, then Utilities), or check **~/Library/Logs/DiagnosticReports** for recent **Libation** crash reports if the process exits abruptly. ### Linux (either the .deb or .rpm installers) The installer creates shortcuts for `libation`, `libationcli`, and `hangover`. From a terminal, run `hangover`. -### Linux: in-app Audible login or “add account” fails +### Linux: in-app Audible login or "add account" fails Embedded sign-in uses WebKit2GTK (`libwebkit2gtk`). If that native stack is missing, install the packages for your distro or use 'external browser' sign-in in Libation's import/library settings. Details: [Install on Linux](/docs/installation/linux) (section: Runtime dependencies (Audible sign-in)). diff --git a/docs/installation/mac.md b/docs/installation/mac.md index 5ffd8ed2..4aa75986 100644 --- a/docs/installation/mac.md +++ b/docs/installation/mac.md @@ -25,6 +25,14 @@ Libation comes with a recovery app called Hangover. You can start it by running open /Applications/Libation.app --args hangover ``` +## Troubleshooting + +See the [macOS section of Troubleshooting](/docs/advanced/troubleshoot#macos) especially when: + +* Libation does not start +* Hangover does not help +* You hit Gatekeeper or quarantine issues + ## Running LibationCli Libation comes with a command-line interface. Unfortunately, due to the way apps are sandboxed on mac, its use is somewhat limited. To open a new sandboxed terminal in LibationCli's directory, run the following command: