Makefile Fixes (sirgwain#573)

Makefile

@@ -1,35 +1,61 @@
-BINARY_NAME=craig-stars
-VERSION=0.0.0-develop
-COMMIT=`git rev-parse HEAD`
-BUILDTIME=$$(date +'%y.%m.%d %H:%M:%S')
+VERSION := 0.0.0-develop
+COMMIT := `git rev-parse HEAD`
 
-# always redo these
-.PHONY: build test clean dev dev_backend dev_frontend
+# detect os type and swap instructions accordingly
+ifeq ($(OS),Windows_NT) 
+# Forcibly swap to powershell if on windows to prevent make from using
+# git's sh.eve instead (which is extremely limited in capabilities) 
+SHELL := powershell.exe
+.SHELLFLAGS := -NoProfile -Command
+BUILDTIME := $(shell Get-Date -Format "yy.MM.dd HH:mm:ss")
+BINARY_NAME := craig-stars.exe
+# conditionals used to mimic behavior on unix-like systems  
+mkdir = if ( -not ( Test-Path $(1) ) ) { mkdir "$(1)" }
+rm = if ( Test-Path $(1) ) { rm -Recurse -Force "$(1)" }
+cp = Copy-Item -Path "$(1)" -Destination "$(2)" -Force
 
-build: build_frontend tidy vendor generate build_server
+else
+# Unix commands
+BUILDTIME := $$(date +'%y.%m.%d %H:%M:%S')
+BINARY_NAME := craig-stars
+mkdir = mkdir -p $(1)
+rm = rm -rf $(1)
+cp = cp $(1) $(2)
+endif
 
-build_frontend:
-	cd frontend && npm install
-	cd frontend && npm run build
+# replaces backslashes with unix-style frontslashes 
+# and strips ending whitespace to allow tacking on backslashes later
+goroot := $(subst \,/,$(shell go env GOROOT))
 
-build_server:
-	mkdir -p dist
-	go build \
+# defined separately to avoid backslash separators affecting recipes 
+build_thing := go build \
 	-o dist/${BINARY_NAME} \
 	-ldflags \
 	"-X 'github.com/sirgwain/craig-stars/cmd.semver=${VERSION}' \
 	-X 'github.com/sirgwain/craig-stars/cmd.commit=${COMMIT}' \
 	-X 'github.com/sirgwain/craig-stars/cmd.buildTime=${BUILDTIME}'" \
 	main.go
 
-build_wasm:
-	mkdir -p frontend/src/lib/wasm
-	GOOS=js GOARCH=wasm \
-	go build \
-	-o frontend/src/lib/wasm/cs.wasm \
-	wasm/main.go
-	cp $(shell go env GOROOT)/misc/wasm/wasm_exec.js ./frontend/src/lib/wasm/wasm_exec.js
+# always redo these
+.PHONY: run build test clean dev dev_backend dev_frontend
+
+run: clean build dev 
+
+build: build_frontend tidy vendor generate build_wasm build_server
 
+build_frontend:
+	cd frontend; npm install; npm run build
+
+build_server:
+	$(call mkdir,dist)
+	$(build_thing)
+
+build_wasm:
+	$(call mkdir,frontend/src/lib/wasm)
+	go env -w GOOS=js GOARCH=wasm; go build -o frontend/src/lib/wasm/cs.wasm wasm/main.go
+	$(call cp,$(goroot)/misc/wasm/wasm_exec.js,./frontend/src/lib/wasm/wasm_exec.js)
+	go env -u GOOS GOARCH
+
 # use docker to build an amd64 image for linux deployment
 build_docker:
 	docker build -f builder.Dockerfile --platform linux/amd64 . -t craig-stars-builder
@@ -40,13 +66,13 @@ generate:
 
 test:
 	go test ./...
-	cd frontend && npm run test
+	cd frontend; npm run test
 
 clean:
 	go clean
-	rm -rf dist
-	rm -rf vendor
-	rm -rf frontend/build
+	$(call rm,dist)
+	$(call rm,vendor)
+	$(call rm,frontend/build)
 
 # uninstall unused modules
 tidy:
@@ -57,11 +83,10 @@ vendor:
 	go mod vendor
 
 dev_frontend:
-	cd frontend && npm run dev
+	cd frontend; npm run dev
 
 dev_backend:
 	air
 
 dev:
 	make -j 2 dev_backend dev_frontend
-

docs/development.md

@@ -24,22 +24,24 @@ For detailed information about `craig-stars` architecture, check out the [archit
 Icons are either hand crafted, taken from the original Stars! files or from the wonderful [game-icons.net](https://game-icons.net) and [heroicons.com](https://heroicons.com).
 
 # Getting Started
-**Note**: The following instructions assume you have `go`, `make` and `npm` installled. `go` can be installed from [their website](https://go.dev/dl/]), while the easiest way to install the other 2 is to use a package manager: [chocolatey](https://chocolatey.org/install) for Windows, [Homebrew](https://brew.sh/) or apt-get/yum for Linux.
+**Note**: The following instructions assume you have `go`, `make` and `npm` installled. `go` can be installed from [their website](https://go.dev/dl/]), while the easiest way to install the other 2 is to use a package manager: [chocolatey](https://chocolatey.org/install) for Windows, [Homebrew](https://brew.sh/) for Mac or apt-get/yum for Linux.
 
 From there, you can install `make` and `node.js` (which includes npm) fairly easily. **Note**: make sure you install the **LTS** version of node. 
 
+If you're on Windows, *make sure to have Powershell installed and in your PATH* for the makefile to function correctly. In 99% of cases, this shouldn't be an issue (powershell is bundled with all currently supported Windows versions to date and has been the default shell since Windows 10), but if your machine somehow doesn't have it, use winget in command prompt (`winget install --id Microsoft.PowerShell --source winget`) to install the latest version. (On Mac/Linux, any terminal should be fine as long as it supports the `mkdir`, `rm`, `cp` and `date` instructions.)
+
 ### GCC
 Additionally, the [go-sqlite3](https://github.com/mattn/go-sqlite3) package `craig-stars` relies on for databasing itself requires the [GNU compiler collection](https://gcc.gnu.org/) to run. You **will** need GCC installed and built to run `craig-stars` locally!
 
 On Linux/Mac, you can simply download the latest version of the GCC compilers using whatever package software you installed previously and build it from there. However, on Windows, you'll need to install a Linux-like development interface (use [MinGW64](https://www.mingw-w64.org/) - Cygwin64 has been known to cause issues) to install/build the latest GCC version due to file type restrictions.
 
 ## Assets
-You will need art assets, and those can be downloaded from [https://craig-stars.net/images/images.zip](https://craig-stars.net/images/images.zip). Copy these images into the `frontend/static/images` folder (or make a new folder if it doesn't already exist).
+You will need art assets for ships and such, and those can be downloaded from [https://craig-stars.net/images/images.zip](https://craig-stars.net/images/images.zip). Copy these images into the `frontend/static/images` folder (or make a new folder if it doesn't already exist).
 
 ## Installing Air
-[Air](https://github.com/air-verse/air) is a Go utility that aids in automatic server restarting. While modifying the frontend code will trigger a hot reload of the local program (allowing for immediate confirmation of changes in real time), changes to the `golang` backend are only reflected the _next_ time the program is launched (requiring you to kill and restart the program each time). `Air` merely automates this "kill and restart" process by shutting down and reloading the server every time changes are detected. 
+[Air](https://github.com/air-verse/air) is a Go utility that aids in automatic server restarting. While modifying the frontend code will trigger a hot reload of the local program (allowing for immediate confirmation of changes in real time), changes to the `golang` backend are only reflected the _next_ time the program is launched (requiring you to kill and restart the program each time). `Air` helps automate this "kill and restart" process by shutting down and reloading the server every time changes are detected. 
 
-Installing air is **not required** to run `craig-stars` locally, but can be helpful if you plan on frequently making changes to the backend and want real time confirmation. 
+Installing air is **not required** to run craig-stars locally, but can be helpful if you plan on frequently making changes to the backend and want real time confirmation.
 
 To install air, enter the following code into your terminal:
 ```bash
@@ -56,14 +58,13 @@ make dev
 
 **Note** On first launch, this will create an empty database with a single `admin` user, password `admin`.
 
-If done correctly, it should give a localhost link (http://localhost:5173/) representing the application being hosted locally on your machine. Go to that site to see a live reloading frontend proxied to the go server on port `:8080`. Updating go code will relaunch the backend automatically (via air), while updating frontend code will do a hot reload with sveltekit/vite.
+If done correctly, it should give a localhost link (http://localhost:5173/) representing the application being hosted locally on your machine. Go to that site to see a live reloading frontend proxied to the go server on port `:8080`. Updating go code will re-launch the backend automatically (via air), while updating frontend code will do a hot reload with sveltekit/vite.
 
 # Visual Studio Code 
-[VS Code](https://code.visualstudio.com) is highly recommended for development. `craig-stars` comes with a [cs.code-workspace](/cs.code-workspace) file that can be opened with VS Code in order to use front end and backend plugins without issue in the same repo. It also comes with a built in terminal, debugging support, and about a thousand other bells and whistles useful for general software development. 
-
+[VS Code](https://code.visualstudio.com) is highly recommended for development. `craig-stars` comes with a [cs.code-workspace](/cs.code-workspace) file that can be opened with VS Code in order to use frontend and backend plugins without issue in the same repo. It also comes with a built in terminal, debugging support, and an array of assorted bells and whistles useful for general software development.
 
 ## backend
-To launch the backend separately from the frontend, you can call `air` directly. 
+To launch the backend separately from the frontend, you can call `air` directly (or equivalently, run the `dev_backend` makefile recipe). 
 
 ```zsh
 ❯ air
@@ -106,13 +107,19 @@ make test
 ```
 
 # Troubleshooting
-"I try to click on the login button on localhost using the admin credentials and it does nothing! Worse, an error pops up in terminal!!!"
+"I try to click on the login button on localhost using the admin credentials and it does nothing! Also, an error pops up in my terminal!"
 
 You probably aren't running the backend. Open a new terminal tab and type `air` to build the backend needed to handle all the nitty gritty logic stuff.
 
 "When I run air, my computer complains about undefined Sqlite Drivers!"
 
 See [Getting started](#Getting Started).
 
-"Make is refusing to follow the instructions in the makefile!"
-If worse comes to worst, try executing the instructions one by one (so do the instructions for make build, then make dev, etc etc). 
+"When I run make build, I get an obscure error about 'executable not found in %PATH%' or 'build target excluding all files in XXX'!"
+What's probably happening is you're trying to generate go files or build the server with the incorrect GOARCH and GOOS settings. Try using `go env -u GOOS GOARCH` to reset them to their defaults and see if the problems persist.
+
+"I tried to do all of the above, but I'm still getting errors in the command line!"
+Consult this ordered checklist of vague general suggestions:
+1. Read the error message to try and figure out why it's failing. Make (as it's being used here) effectively just copy-pastes its commands into the terminal one by one (expanding variables here and there), so syntax errors in the terminal can oftentimes reflect issues with the makefile itself rather than any device-related issues. 
+2. Try and search online for the error message or similar problems to see if others may have found solutions to the problem for you. 
+3. If all else fails, reach out in the #stars-clones or #craig-stars channels in the discord (ideally with images/text of the commands used and/or resulting error messages).