From cf9df8437c90d8251f39d1affbf04142fd2282bb Mon Sep 17 00:00:00 2001
From: Martin Kinkelin <noone@nowhere.com>
Date: Fri, 15 Dec 2023 23:13:23 +0100
Subject: [PATCH] Makefiles: Add comments wrt. usage on Windows and a few
 example invocations

---
 Makefile                        | 19 +++++++++++++++++++
 changelog/druntime.makefiles.dd |  2 +-
 druntime/Makefile               | 16 +++++++++++++---
 3 files changed, 33 insertions(+), 4 deletions(-)

diff --git a/Makefile b/Makefile
index bb3b1c010c..9d208178c7 100644
--- a/Makefile
+++ b/Makefile
@@ -1,3 +1,22 @@
+# This makefile is designed to be run by gnu make.
+# - Windows: you may download a prebuilt zipped .exe from https://github.com/dlang/dmd/releases/download/nightly/gnumake-4.4-win64.zip.
+#   You also need a Git for Windows installation, for bash and common GNU tools like cp,mkdir,mv,rm,touch,which.
+# - FreeBSD: the default make program on FreeBSD is not gnu make; to install gnu make:
+#     pkg install gmake
+#   and then run as gmake rather than make.
+#
+# Examples:
+# - Build compiler (unoptimized) and druntime:
+#     make -j$(nproc)
+# - Build compiler (optimized) and druntime using an LDC host compiler:
+#     make -j$(nproc) HOST_DMD=ldmd2 ENABLE_RELEASE=1 [ENABLE_LTO=1]
+# - Build and run druntime tests:
+#     make -j$(nproc) druntime-test
+# - Run compiler tests (needs a built Phobos as prerequisite):
+#     make -j$(nproc) dmd-test
+#
+# See compiler/src/build.d for variables affecting the compiler build.
+
 include compiler/src/osmodel.mak
 
 INSTALL_DIR=$(shell pwd)/../install
diff --git a/changelog/druntime.makefiles.dd b/changelog/druntime.makefiles.dd
index 6af0de0ac3..06fb6af972 100644
--- a/changelog/druntime.makefiles.dd
+++ b/changelog/druntime.makefiles.dd
@@ -2,4 +2,4 @@ Makefiles cleanup for druntime
 
 The `{posix,win32,win64}.mak` Makefiles have been merged to a generic `Makefile` (including the ones in `druntime/test/`). `posix.mak` is kept as a deprecated forwarder for now.
 
-On Windows, you can/need to use the generic Makefile too - with a GNU make (and a git installation providing bash and GNU tools). Windows devs can finally exploit parallelism via `-j`! (Version [4.2.1](https://ftp.gnu.org/gnu/make/make-4.2.1.tar.bz2) is the latest version coming with a Visual Studio `.sln`, to quickly build it yourself.)
+On Windows, you can/need to use the generic Makefile too - with a GNU make (and a git installation providing bash and GNU tools). Windows devs can finally exploit parallelism via `-j`! You may download a prebuilt zipped .exe from https://github.com/dlang/dmd/releases/download/nightly/gnumake-4.4-win64.zip.
diff --git a/druntime/Makefile b/druntime/Makefile
index 361d0eb5c0..ed69d01670 100644
--- a/druntime/Makefile
+++ b/druntime/Makefile
@@ -1,7 +1,17 @@
 # This makefile is designed to be run by gnu make.
-# The default make program on FreeBSD 8.1 is not gnu make; to install gnu make:
-#    pkg_add -r gmake
-# and then run as gmake rather than make.
+# - Windows: you may download a prebuilt zipped .exe from https://github.com/dlang/dmd/releases/download/nightly/gnumake-4.4-win64.zip.
+#   You also need a Git for Windows installation, for bash and common GNU tools like cp,mkdir,mv,rm,touch,which.
+# - FreeBSD: the default make program on FreeBSD is not gnu make; to install gnu make:
+#     pkg install gmake
+#   and then run as gmake rather than make.
+#
+# Examples:
+# - Build druntime:
+#     make -j$(nproc)
+# - Build and run druntime tests:
+#     make -j$(nproc) unittest
+# - Build and run druntime tests in debug mode only:
+#     make -j$(nproc) unittest-debug
 
 QUIET:=