Skip to content

armgit / nota

Public Imported from GitHub
0

Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.

(fix) Linux: one settings folder, ~/.config/nota (#86)

Egor Khindikaynenb76651987cd6
diff --git a/.specify/bugs/linux-config-dir-case/assessment.md b/.specify/bugs/linux-config-dir-case/assessment.md
new file mode 100644
index 00000000..18b86f28
--- /dev/null
+++ b/.specify/bugs/linux-config-dir-case/assessment.md
@@ -0,0 +1,98 @@
+# Bug Assessment: Linux per-user data split across ~/.config/nota and ~/.config/Nota
+
+- **Slug**: linux-config-dir-case
+- **Created**: 2026-10-15
+- **Source**: pasted text (user observation)
+- **Verdict**: valid
+- **Severity**: medium
+
+## Report (verbatim or summarized)
+
+> Заметил проблему, что создаются такие директории с файлами: часть в ~/.config/nota, а часть в ~/.config/Nota
+
+(Noticed that directories with files are created in two places: some in `~/.config/nota`,
+some in `~/.config/Nota`.)
+
+## Symptom
+
+On Linux Nota keeps its per-user files in two folders. The managed layer writes settings,
+logs, recovery and presets to `~/.config/nota`, while the native engine writes `audio.json`,
+`midi.json`, `plugins.xml` and `scanpaths.txt` to `~/.config/Nota`. Expected: one folder.
+Linux filesystems are case-sensitive, so these really are two different directories.
+
+## Reproduction
+
+1. Run Nota on Linux (no `NOTA_DATA_DIR`).
+2. Change the audio device in Preferences, or scan plugins.
+3. `ls ~/.config` shows both `nota/` (settings.json, logs/, …) and `Nota/` (audio.json,
+ midi.json, plugins.xml, scanpaths.txt).
+
+## Suspected Code Paths
+
+- `src/managed/Nota.Infrastructure/NotaPaths.cs:52`: Linux root is `<XDG_CONFIG_HOME|~/.config>/nota` (lowercase).
+- `src/native/nota.engine/src/NotaConfigFile.cpp:102` (`cfgfile::dataDir`): appends `"Nota"` on Linux; used by `AudioConfig_miniaudio.cpp` and `MidiConfig_rtmidi.cpp`.
+- `src/native/nota.engine/pluginhost/PluginHost.cpp:146` (`notaSupportDir`): JUCE `userApplicationDataDirectory` (resolves `XDG_CONFIG_HOME` / `~/.config`) + `"Nota"`.
+- Comments repeat the split: `NotaConfigFile.h:10` and `PluginHost.cpp:129` say `Nota`, `NotaPaths.cs:9` says `nota`.
+- `.github/ISSUE_TEMPLATE/bug_report.yml:69` tells users that Linux logs live in `~/.config/nota/logs/`.
+
+Related: `cfgfile::dataDir` ignores `NOTA_DATA_DIR`, but `NotaPaths` and `notaSupportDir`
+honour it. So on Windows and Linux, test runs still write audio.json and midi.json into the
+real user folder.
+
+## Root Cause Hypothesis
+
+Both casings go back to the first commit (e5e2a5bf). When the native config layer was
+written, the casing was mirrored from Windows/macOS (`Nota`). The managed layer, though,
+followed the XDG lowercase convention on Linux. This only shows up on case-sensitive
+filesystems. Confidence: high.
+
+## Proposed Remediation
+
+**Preferred**: make lowercase `nota` the single Linux folder (decided with the user). It
+matches XDG convention, it already holds most of the data, and it is what the issue template
+documents.
+
+- `cfgfile::dataDir()`: honour `NOTA_DATA_DIR` first, like `NotaPaths`. On Linux use
+ `<root>/nota`. On Windows keep `%APPDATA%\Nota`.
+- One-time migration on Linux: if `<root>/Nota` exists and is not the same directory as
+ `<root>/nota`, move each entry into `nota/` unless it is already there. Then remove
+ `Nota/` if it is empty. Never overwrite anything, and keep the work best-effort
+ (`error_code` overloads). Run it once per process with a static guard.
+- `PluginHost.cpp notaSupportDir()`: off macOS, delegate to `nota::cfgfile::dataDir()`
+ (its header is already on the pluginhost include path, and the library links into
+ `nota_engine`, which compiles `NotaConfigFile.cpp` on Windows and Linux). That leaves one
+ resolver for the native config files, with the migration in it.
+- Fix the comments in `NotaConfigFile.h`, `PluginHost.cpp` and `NotaPaths.cs`.
+
+**Alternatives**:
+- Switch managed to `Nota`. This moves the larger data set and contradicts the published
+ issue template. Rejected.
+- Skip the migration. Existing Linux users would lose their audio and MIDI device choice and
+ their plugin catalog (a rescan). That is cheap to avoid.
+
+**Files likely to change**:
+- `src/native/nota.engine/src/NotaConfigFile.cpp`
+- `src/native/nota.engine/src/NotaConfigFile.h`
+- `src/native/nota.engine/pluginhost/PluginHost.cpp`
+- `src/managed/Nota.Infrastructure/NotaPaths.cs` (comment only)
+- `CHANGELOG.md` ([Unreleased] → Fixed)
+
+**Tests to add or update**:
+- The smoke test runs on macOS, where this code path is not compiled (macOS uses
+ `~/Library/Application Support/Nota`). Verification is a Linux build plus a manual check:
+ `XDG_CONFIG_HOME=/tmp/x`, seed `/tmp/x/Nota/audio.json`, then start the engine and
+ confirm the file moved to `/tmp/x/nota/`.
+
+## Risks & Considerations
+
+- Case-insensitive filesystem on Linux (rare): `Nota` and `nota` are the same directory, so
+ the `equivalent()` check must skip the migration.
+- A file present in both folders: keep the `nota/` copy and leave the legacy one in place
+ (`Nota/` is then not removed). No data loss.
+- Windows and macOS paths are unchanged.
+- `dataDir()` is called on config load/save (message thread), never on the audio thread.
+ Filesystem work there is fine.
+
+## Open Questions
+
+- None.
diff --git a/.specify/bugs/linux-config-dir-case/fix.md b/.specify/bugs/linux-config-dir-case/fix.md
new file mode 100644
index 00000000..ba01c519
--- /dev/null
+++ b/.specify/bugs/linux-config-dir-case/fix.md
@@ -0,0 +1,64 @@
+# Bug Fix: Linux per-user data split across ~/.config/nota and ~/.config/Nota
+
+- **Slug**: linux-config-dir-case
+- **Fixed**: 2026-10-15
+- **Assessment**: ./assessment.md
+- **Status**: applied
+
+## Summary
+
+The native engine now uses the same lowercase `nota` folder on Linux as the managed layer.
+On first use it moves what an earlier build left in `Nota/` into `nota/`, never
+overwriting. The plugin host now takes its folder from the same resolver. `cfgfile::dataDir`
+now honours `NOTA_DATA_DIR`.
+
+## Changes
+
+| File | Change | Notes |
+|------|--------|-------|
+| `src/native/nota.engine/src/NotaConfigFile.cpp` | modified | `NOTA_DATA_DIR` override; Linux folder `nota`; one-time `migrateLegacyDir(<root>/Nota → <root>/nota)` behind a static guard |
+| `src/native/nota.engine/src/NotaConfigFile.h` | modified | comment: Linux path, `NOTA_DATA_DIR`, plugin catalog lives here |
+| `src/native/nota.engine/pluginhost/PluginHost.cpp` | modified | off macOS, `notaSupportDir()` returns `cfgfile::dataDir()` (include guarded by `__APPLE__`, since `JUCE_MAC` isn't defined before the JUCE headers) |
+| `src/managed/Nota.Infrastructure/NotaPaths.cs` | modified | comment only |
+| `CHANGELOG.md` | modified | [Unreleased] → Fixed entry |
+
+## Diff Highlights
+
+```cpp
+// NotaConfigFile.cpp — Linux
+std::filesystem::path dir = root / "nota";
+...
+static const bool migrated = (migrateLegacyDir(root / "Nota", dir), true);
+```
+
+`migrateLegacyDir` skips the move when the two paths are the same directory
+(`std::filesystem::equivalent`, case-insensitive FS). It renames each entry only if the
+target is absent, then calls `remove(legacy)`, which succeeds only when the folder is empty.
+
+## Tests Added or Updated
+
+- No automated test. The code path is compiled only on Windows/Linux, and the smoke test
+ runs on macOS, where the data dir is `~/Library/Application Support/Nota`. Checked with
+ a throwaway harness instead (below).
+
+## Local Verification
+
+- A throwaway harness (`dataDir()` printed, built with clang++ -std=c++20 -Wall -Wextra
+ against `NotaConfigFile.cpp`, which takes the non-Windows branch on macOS):
+ - Case-sensitive APFS image, `XDG_CONFIG_HOME` set:
+ - Both folders present: `audio.json` and `plugins.xml` moved to `nota/`.
+ `nota/settings.json` was kept; the legacy `settings.json` stayed in `Nota/`.
+ - Only `Nota/` present: files moved and `Nota/` removed.
+ - Case-insensitive APFS: the `equivalent()` guard skipped the move and the files stayed
+ in place.
+ - `NOTA_DATA_DIR` set: that folder was returned and created.
+- `scripts/build.sh` (macOS) → exit 0, SMOKE TEST PASSED (the macOS PluginHost.cpp branch compiles; Windows/Linux branches not compiled here).
+
+## Deviations from Assessment
+
+None.
+
+## Follow-ups
+
+- Run a Linux build (`scripts/build-linux.sh` or CI) to compile the `PluginHost.cpp` branch
+ that does not compile on macOS.
diff --git a/.specify/bugs/linux-config-dir-case/test.md b/.specify/bugs/linux-config-dir-case/test.md
new file mode 100644
index 00000000..7fd124aa
--- /dev/null
+++ b/.specify/bugs/linux-config-dir-case/test.md
@@ -0,0 +1,52 @@
+# Bug Verification: Linux per-user data split across ~/.config/nota and ~/.config/Nota
+
+- **Slug**: linux-config-dir-case
+- **Tested**: 2026-10-15
+- **Assessment**: ./assessment.md
+- **Fix**: ./fix.md
+- **Result**: verified
+
+## Summary
+
+On a real Linux build (Docker, `mcr.microsoft.com/dotnet/sdk:10.0`, arm64), a Nota run that
+starts with old engine files in `~/.config/Nota` ends with a single `~/.config/nota`. The
+legacy files were moved in with their contents intact, and `~/.config/Nota` was removed. The
+Linux and macOS builds and their smoke tests pass, with no regressions.
+
+## Checks Performed
+
+| Check | Command / Action | Result | Notes |
+|-------|------------------|--------|-------|
+| Reproduction (post-fix, Linux) | Seed `/root/.config/Nota/{audio.json,plugins.xml,scanpaths.txt}`, `NOTA_DATA_DIR` unset, run `scripts/build-linux.sh` (its smoke test drives the engine) | pass | Afterwards only `/root/.config/nota/` exists; it holds the migrated files plus the managed side's `analysis-cache`, `kits`, `grain-sources`, `mosaic-sources`. `scanpaths.txt` still reads `/opt/legacy-vst3` |
+| Linux compile of changed TUs | same run | pass | `NotaConfigFile.cpp.o` and `pluginhost/PluginHost.cpp.o` built, no errors/warnings in them |
+| Migration edge cases | throwaway harness on a case-sensitive APFS image + default APFS (see fix.md) | pass | no-overwrite on conflict, legacy dir kept when not empty, case-insensitive FS untouched, `NOTA_DATA_DIR` honoured |
+| Regression suite (Linux) | `scripts/build-linux.sh` | pass | `SMOKE TEST PASSED` |
+| Regression suite (macOS) | `scripts/build.sh` | pass | `SMOKE TEST PASSED` |
+| Windows build | — | not-run | No Windows host; the Windows path is unchanged in behaviour (`%APPDATA%\Nota`), but the plugin host now gets it from `cfgfile::dataDir()` instead of JUCE |
+
+## Output Excerpts
+
+```
+build rc=0
+[33/155] Building CXX object CMakeFiles/nota_engine.dir/src/NotaConfigFile.cpp.o
+[37/155] Building CXX object CMakeFiles/nota_pluginhost.dir/pluginhost/PluginHost.cpp.o
+SMOKE TEST PASSED
+--- ~/.config after the smoke test:
+/root/.config/nota/:
+analysis-cache audio.json grain-sources kits mosaic-sources plugins.xml scanpaths.txt
+scanpaths:
+/opt/legacy-vst3
+```
+
+## Residual Risks
+
+- Windows was not compiled or run. The plugin catalog path should be the same as before
+ (`$APPDATA` vs JUCE's `SHGetSpecialFolderPath(CSIDL_APPDATA)`), but CI should confirm it.
+- The first container run hit an OOM in the JUCE compile at default parallelism (8 GB Docker
+ VM). This is an environment limit: `CMAKE_BUILD_PARALLEL_LEVEL=4` fixed it. Not related to
+ the fix.
+
+## Recommendation
+
+Close the bug: verified end-to-end on Linux. Let Windows CI confirm the plugin-host path
+before merging.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3860e8b4..7f015cd2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -95,6 +95,10 @@ Entry categories: `Added`, `Changed`, `Fixed`, `Removed`.
chain.
### Fixed
+- **One settings folder on Linux:** Nota kept its files in two folders, `~/.config/nota`
+ and `~/.config/Nota`; the audio and MIDI device choice and the plugin list went to the
+ second. Everything now lives in `~/.config/nota` (or `$XDG_CONFIG_HOME/nota`), and on the
+ first launch Nota moves the files over from `~/.config/Nota` — nothing to set up again.
- **Popping out the piano roll no longer crashes on Linux:** opening Devices / Clip in its
own window could close Nota at once on Linux ("Attempt to call InvalidateArrange on wrong
LayoutManager"). The editor's pending layout in the main window is now finished before it
diff --git a/src/managed/Nota.Infrastructure/NotaPaths.cs b/src/managed/Nota.Infrastructure/NotaPaths.cs
index 884631d3..491d1d01 100644
--- a/src/managed/Nota.Infrastructure/NotaPaths.cs
+++ b/src/managed/Nota.Infrastructure/NotaPaths.cs
@@ -6,8 +6,8 @@
// audio.json / midi.json writers). Platform conventions:
// macOS -> ~/Library/Application Support/Nota (unchanged from the mac-only era)
// Windows -> %APPDATA%\Nota (Roaming AppData)
-// Linux -> $XDG_CONFIG_HOME/nota or ~/.config/nota
-// The native side resolves the same locations (SHGetKnownFolderPath / NSHomeDirectory)
+// Linux -> $XDG_CONFIG_HOME/nota or ~/.config/nota (lowercase, XDG style)
+// The native side resolves the same locations (cfgfile::dataDir, the plugin host)
// so config written by C++ and C# lands in one place.
namespace Nota.Infrastructure;
diff --git a/src/native/nota.engine/pluginhost/PluginHost.cpp b/src/native/nota.engine/pluginhost/PluginHost.cpp
index 0b84f33c..5168c870 100644
--- a/src/native/nota.engine/pluginhost/PluginHost.cpp
+++ b/src/native/nota.engine/pluginhost/PluginHost.cpp
@@ -17,6 +17,9 @@
#include "Instrument.h"
#include "PluginHostBridge.h"
#include "CommandQueue.h" // SpscRingBuffer: message-thread -> audio-thread note injection
+#if !defined(__APPLE__) // JUCE_MAC is not defined yet: the JUCE headers come below
+#include "NotaConfigFile.h" // cfgfile::dataDir: the Windows/Linux per-user data dir
+#endif
#include <juce_audio_processors/juce_audio_processors.h>
#include <juce_gui_basics/juce_gui_basics.h>
@@ -126,7 +129,7 @@ juce::KnownPluginList& catalog() {
// Per-user Nota data dir (mirrors NotaPaths.DataDir / cfgfile::dataDir):
// macOS -> ~/Library/Application Support/Nota
// Windows -> %APPDATA%\Nota
-// Linux -> ~/.config/Nota
+// Linux -> $XDG_CONFIG_HOME/nota or ~/.config/nota
juce::File notaSupportDir() {
// NOTA_DATA_DIR (tests) relocates the catalog + scan paths, like NotaPaths.DataDir.
// Needed because on macOS JUCE resolves the home folder via NSHomeDirectory(), not $HOME.
@@ -139,14 +142,12 @@ juce::File notaSupportDir() {
auto dir = juce::File::getSpecialLocation(juce::File::userApplicationDataDirectory)
.getChildFile("Application Support")
.getChildFile("Nota");
-#else
- // On Windows userApplicationDataDirectory resolves to %APPDATA%; on Linux to
- // ~/.config (matching cfgfile::dataDir's XDG default).
- auto dir = juce::File::getSpecialLocation(juce::File::userApplicationDataDirectory)
- .getChildFile("Nota");
-#endif
dir.createDirectory();
return dir;
+#else
+ // Windows + Linux share the engine's config dir (same folder as audio.json / midi.json).
+ return juce::File{juce::CharPointer_UTF8(nota::cfgfile::dataDir().c_str())};
+#endif
}
juce::File catalogFile() { return notaSupportDir().getChildFile("plugins.xml"); }
diff --git a/src/native/nota.engine/src/NotaConfigFile.cpp b/src/native/nota.engine/src/NotaConfigFile.cpp
index 6a3d05ec..2074ce6e 100644
--- a/src/native/nota.engine/src/NotaConfigFile.cpp
+++ b/src/native/nota.engine/src/NotaConfigFile.cpp
@@ -82,26 +82,55 @@ size_t findValue(const std::string& json, const std::string& key) {
return skipWs(json, p + 1);
}
+#if !defined(_WIN32)
+// Earlier engine builds wrote audio.json / midi.json / plugins.xml / scanpaths.txt to
+// <root>/Nota while the managed side used <root>/nota. Move what is there into the one
+// folder, never overwriting, and drop the old folder once it is empty. Best-effort.
+void migrateLegacyDir(const std::filesystem::path& legacy, const std::filesystem::path& dir) {
+ std::error_code ec;
+ if (!std::filesystem::is_directory(legacy, ec)) return;
+ if (std::filesystem::equivalent(legacy, dir, ec)) return; // case-insensitive filesystem
+ for (const auto& entry : std::filesystem::directory_iterator(legacy, ec)) {
+ auto target = dir / entry.path().filename();
+ if (!std::filesystem::exists(target, ec))
+ std::filesystem::rename(entry.path(), target, ec);
+ }
+ std::filesystem::remove(legacy, ec); // only succeeds if empty
+}
+#endif
+
} // namespace
std::string dataDir() {
- // Resolve the per-user config root, then append "Nota". Windows: %APPDATA%.
- // Linux: $XDG_CONFIG_HOME, else $HOME/.config (XDG Base Directory spec) —
- // mirrors NotaPaths.DataDir on the managed side.
+ // NOTA_DATA_DIR (tests) relocates the data root, like NotaPaths.DataDir.
+ if (const char* over = std::getenv("NOTA_DATA_DIR"); over && *over) {
+ std::error_code ec;
+ std::filesystem::create_directories(over, ec);
+ return over;
+ }
+ // Resolve the per-user config root, then append the app folder — mirrors
+ // NotaPaths.DataDir on the managed side. Windows: %APPDATA%\Nota.
+ // Linux: $XDG_CONFIG_HOME, else $HOME/.config (XDG Base Directory spec), + "nota".
std::filesystem::path root;
#if defined(_WIN32)
if (const char* appdata = std::getenv("APPDATA"); appdata && *appdata)
root = appdata;
+ if (root.empty()) return {};
+ std::filesystem::path dir = root / "Nota";
#else
if (const char* xdg = std::getenv("XDG_CONFIG_HOME"); xdg && *xdg)
root = xdg;
else if (const char* home = std::getenv("HOME"); home && *home)
root = std::filesystem::path(home) / ".config";
-#endif
if (root.empty()) return {};
- std::filesystem::path dir = root / "Nota";
+ std::filesystem::path dir = root / "nota";
+#endif
std::error_code ec;
std::filesystem::create_directories(dir, ec);
+#if !defined(_WIN32)
+ static const bool migrated = (migrateLegacyDir(root / "Nota", dir), true);
+ (void)migrated;
+#endif
return dir.string();
}
diff --git a/src/native/nota.engine/src/NotaConfigFile.h b/src/native/nota.engine/src/NotaConfigFile.h
index ad4bb784..a811c1b2 100644
--- a/src/native/nota.engine/src/NotaConfigFile.h
+++ b/src/native/nota.engine/src/NotaConfigFile.h
@@ -7,8 +7,8 @@
// engine-internal (the managed layer reads them only through C ABI getters), so a
// hand-rolled parser is sufficient — but string values (WASAPI endpoint ids can contain
// backslashes/braces) are properly escaped. The directory mirrors NotaPaths.DataDir on
-// the managed side: %APPDATA%\Nota on Windows, $XDG_CONFIG_HOME/Nota (or ~/.config/Nota)
-// on Linux.
+// the managed side: %APPDATA%\Nota on Windows, $XDG_CONFIG_HOME/nota (or ~/.config/nota)
+// on Linux, or NOTA_DATA_DIR when set (tests). The plugin host's catalog lives here too.
#pragma once