docs: misc, build, lsp

1 files changed, 41 insertions, 27 deletions

diff --git a/BUILD.md b/BUILD.md
index 98e1136331..a7c1821c9e 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -120,12 +120,22 @@ To build from the command line (i.e. invoke the `cmake` commands yourself),
 
 ### Windows / Cygwin
 
-Install all dependencies the normal way, then build Neovim the normal way for a random CMake application (i.e. do not use the `Makefile` that automatically downloads and builds "bundled" dependencies).
+Since https://github.com/neovim/neovim/pull/36417 , building on Cygwin may be as easy as:
 
-The `cygport` repo contains Cygport files (e.g. `APKBUILD`, `PKGBUILD`) for all the dependencies not available in the Cygwin distribution, and describes any special commands or arguments needed to build. The Cygport definitions also try to describe the required dependencies for each one. Unless custom commands are provided, Cygport just calls `autogen`/`cmake`, `make`, `make install`, etc. in a clean and consistent way.
+    make && make install
 
-https://github.com/cascent/neovim-cygwin was built on Cygwin 2.9.0. Newer `libuv` should require slightly less patching. Some SSP stuff changed in Cygwin 2.10.0, so that might change things too when building Neovim.
+If that fails, an alternative is:
 
+1. Install all dependencies the normal way.
+    - The `cygport` repo contains Cygport files (e.g. `APKBUILD`, `PKGBUILD`) for all the dependencies not available in the Cygwin distribution, and describes any special commands or arguments needed to build. The Cygport definitions also try to describe the required dependencies for each one. Unless custom commands are provided, Cygport just calls `autogen`/`cmake`, `make`, `make install`, etc. in a clean and consistent way.
+    - https://github.com/cascent/neovim-cygwin was built on Cygwin 2.9.0. Newer `libuv` should require slightly less patching. Some SSP stuff changed in Cygwin 2.10.0, so that might change things too when building Neovim.
+2. Build without "bundled" dependencies (except treesitter parsers).
+   ```
+   cmake -S cmake.deps -B .deps -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo -DUSE_BUNDLED=OFF -DUSE_BUNDLED_TS=ON
+   cmake --build .deps
+   cmake -B build -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo
+   cmake --build build
+   ```
 
 ### Windows / MSYS2 / MinGW
 
@@ -268,7 +278,7 @@ cmake -B build -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo
 cmake --build build
 ```
 
-### How to build without "bundled" dependencies
+### Build without "bundled" dependencies
 
 1. Manually install the dependencies:
     - libuv libluv libutf8proc luajit lua-lpeg tree-sitter tree-sitter-c tree-sitter-lua tree-sitter-markdown tree-sitter-query tree-sitter-vim tree-sitter-vimdoc unibilium
@@ -288,7 +298,24 @@ cmake --build build
     - Using `ninja` is strongly recommended.
 4. If treesitter parsers are not bundled, they need to be available in a `parser/` runtime directory (e.g. `/usr/share/nvim/runtime/parser/`).
 
-### How to build without unibilium
+### Build offline
+
+On systems with old or missing libraries, *without* network access, you may want
+to build *with* bundled dependencies. This is supported as follows.
+
+1. On a network-enabled machine, do either of the following, to get the
+   dependency sources in `.deps` in a form that the build will work with:
+    - Fetch https://github.com/neovim/deps/tree/master/src into `.deps/build/src/`.
+      (https://github.com/neovim/deps/tree/master/src is an auto-updated, "cleaned up", snapshot of `.deps/build/src/`).
+    - Run `make deps` to generate `.deps/`, then clean it up using [these commands](https://github.com/neovim/neovim/blob/1c12073db6c64eb365748f153f96be9b0fe61070/.github/workflows/build.yml#L67-L74).
+2. Copy the prepared `.deps` to the isolated machine (without network access).
+3. Build with `USE_EXISTING_SRC_DIR` enabled, on the isolated machine:
+   ```
+   make deps DEPS_CMAKE_FLAGS=-DUSE_EXISTING_SRC_DIR=ON
+   make
+   ```
+
+### Build without unibilium
 
 Unibilium is the only dependency which is licensed under LGPLv3 (there are no
 GPLv3-only dependencies). This library is used for loading the terminfo database at
@@ -302,7 +329,15 @@ make CMAKE_EXTRA_FLAGS="-DENABLE_UNIBILIUM=0" DEPS_CMAKE_FLAGS="-DUSE_BUNDLED_UN
 
 To confirm at runtime that unibilium was not included, check `has('terminfo') == 1`.
 
-### How to build static binary (on Linux)
+### Build with specific "bundled" dependencies
+
+Example of building with specific bundled and non-bundled dependencies:
+
+```
+make DEPS_CMAKE_FLAGS="-DUSE_BUNDLED=OFF -DUSE_BUNDLED_LUV=ON -DUSE_BUNDLED_TS=ON -DUSE_BUNDLED_LIBUV=ON"
+```
+
+### Build static binary (Linux)
 
 1. Use a linux distribution which uses musl C. We will use Alpine Linux but any distro with musl should work. (glibc does not support static linking)
 2. Run make passing the `STATIC_BUILD` variable: `make CMAKE_EXTRA_FLAGS="-DSTATIC_BUILD=1"`
@@ -325,27 +360,6 @@ The resulting binary in `build/bin/nvim` will have all the dependencies statical
 build/bin/nvim: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), statically linked, BuildID[sha1]=b93fa8e678d508ac0a76a2e3da20b119105f1b2d, with debug_info, not stripped
 ```
 
-#### Debian 10 (Buster) example:
-
-```sh
-sudo apt install luajit libluajit-5.1-dev lua-lpeg libunibilium-dev
-cmake -S cmake.deps -B .deps -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo -DUSE_BUNDLED=OFF -DUSE_BUNDLED_LIBUV=ON -DUSE_BUNDLED_LUV=ON -DUSE_BUNDLED_TS=ON -DUSE_BUNDLED_UTF8PROC=ON
-cmake --build .deps
-cmake -B build -G Ninja -D CMAKE_BUILD_TYPE=RelWithDebInfo
-cmake --build build
-```
-
-#### Example of using a Makefile
-
-- Example of using a package with all dependencies:
-  ```
-  make USE_BUNDLED=OFF
-  ```
-- Example of using a package with some dependencies:
-  ```
-  make DEPS_CMAKE_FLAGS="-DUSE_BUNDLED=OFF -DUSE_BUNDLED_LUV=ON -DUSE_BUNDLED_TS=ON -DUSE_BUNDLED_LIBUV=ON"
-  ```
-
 ## Build prerequisites
 
 General requirements (see [#1469](https://github.com/neovim/neovim/issues/1469#issuecomment-63058312)):