From dbc6acc8fb6b98ad3ce3b9a415f6a5566471eb66 Mon Sep 17 00:00:00 2001
From: YoshiRulz <OSSYoshiRulz+git@gmail.com>
Date: Fri, 5 Jul 2024 22:33:05 +1000
Subject: [PATCH] Nix expr: Document nix-shell for dev and Kate

---
 Dist/nix_expr_usage_docs.md | 27 ++++++++++++++++++++++++++-
 README.md                   |  2 ++
 contributing.md             |  1 +
 shell.nix                   |  1 -
 4 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/Dist/nix_expr_usage_docs.md b/Dist/nix_expr_usage_docs.md
index c4d5ebe03d..f7577a7894 100644
--- a/Dist/nix_expr_usage_docs.md
+++ b/Dist/nix_expr_usage_docs.md
@@ -49,7 +49,7 @@ There are a few parameters you can tweak without writing a full Nix expression:
 - `--argstr buildConfig Debug` builds the BizHawk solution in Debug configuration.
 - `--argstr extraDefines "CoolFeatureFlag"` adds to `<DefineConstants/>`.
 - `--arg initConfig {}` can be used to set up keybinds and such, though you probably won't want to use `--arg` for that.
-- Check the source for the full list.
+- Check [the source](default.nix) for the full list.
 
 Every installable can also be used with `nix-shell`. Omitting `-A` is the same as `nix-shell -A emuhawk-latest`.
 <!-- TODO haven't implemented LSPs
@@ -86,3 +86,28 @@ emuhawk-monort-local # = `cd output && mono EmuHawk.exe`
 # if deps (besides NuGet packages) have changed, may need to do this instead, but it will do a slow copy of the repo to the Nix store
 nix-shell -A emuhawk
 ```
+
+## IDE setup
+
+### Kate
+
+Syntax highlighting is built-in, and autocomplete, static analysis, and navigation are provided by OmniSharp (LSP).
+Build/test configurations aren't set up.
+
+```sh
+nix-shell --arg useKate true
+Dist/BuildDebug.sh # populate build cache
+kate src/BizHawk.Common/VersionInfo.cs &
+```
+
+Some of our source files are long and our projects are large, so the LSP client can be slow at times.
+
+The scroll position for the syntax highlighting can become desynced from that of the text, leading to syntax getting multiple and/or incorrect colours.
+
+Kate is not a .NET IDE and doesn't understand the Solution/Project structure or any MSBuild metadata; it sees only C# source files, and shows every file in the Git repo.
+
+### VS Code / Codium
+
+Not yet implemented.
+
+There is a `.vs` dir in the repo, but it's outdated.
diff --git a/README.md b/README.md
index 3bf494138d..f46e11768a 100644
--- a/README.md
+++ b/README.md
@@ -162,6 +162,8 @@ Dev builds and a few recent releases can be built with Nix, either by cloning th
 See the [dedicated Nix usage readme](Dist/nix_expr_usage_docs.md) for what attributes are exposed.
 If you use a non-NixOS distro with Nix installed, you just need to add one argument and your host graphics drivers will be picked up thanks to nixGL.
 
+You can also quickly get a development setup, including the .NET SDK and an IDE, with the provided `shell.nix`. See the [Nix-specific docs](Dist/nix_expr_usage_docs.md#ide-setup) for details.
+
 [to top](#bizhawk)
 
 ### Development builds
diff --git a/contributing.md b/contributing.md
index 9475b06570..5f5471dac1 100644
--- a/contributing.md
+++ b/contributing.md
@@ -70,6 +70,7 @@ It's probably a good idea to get the .NET SDK, even if you're not working on a .
 - Linux
 	- Install the .NET 8 SDK (package name is usually `dotnet-sdk-8.0`, see [full instructions](https://learn.microsoft.com/en-gb/dotnet/core/install/linux)).
 	- VS Community isn't available for Linux, but Rider and VS Code are.
+	- Nix/NixOS users can get the .NET SDK ephemerally with the provided `shell.nix`. For IDE setup and more, see the [Nix-specific docs](Dist/nix_expr_usage_docs.md#ide-setup).
 - macOS
 	- Note that EmuHawk does not currently support macOS.
 	- Install the .NET 8 SDK [manually](https://learn.microsoft.com/en-gb/dotnet/core/install/macos) or with Homebrew.
diff --git a/shell.nix b/shell.nix
index c238bf5542..d92ad497c2 100644
--- a/shell.nix
+++ b/shell.nix
@@ -13,7 +13,6 @@
 , useNanoAndCola ? false
 , useVSCode ? false
 }: let
-	# thinking of exposing pre-configured IDEs from `default.nix` so they're available here
 	avail = import ./. { inherit debugDotnetHostCrashes debugPInvokes forNixOS system; };
 	f = drv: mkShell {
 		packages = [ git powershell ]