makefile-improvements.md

@@ -0,0 +1,114 @@
+# Makefile Improvements
+
+This document lists the issues identified in the original Makefile and the improvements that were implemented.
+
+## Issues Fixed
+
+### 1. Hardcoded `.exe` extension on Unix
+**Problem**: `BINARY_NAME=lambda.exe` used a Windows extension on macOS/Linux systems.
+
+**Solution**: Changed to `BINARY_NAME=lambda` since Unix executables don't use extensions.
+
+**Commit**: `0d06fac` - fix: remove Windows .exe extension from binary name
+
+---
+
+### 2. Redundant `chmod +x`
+**Problem**: The `chmod +x` command was unnecessary since `go build` already sets the executable bit.
+
+**Solution**: Removed the redundant `chmod +x ${BINARY_NAME}` line.
+
+**Commit**: `e0b0b92` - refactor: remove redundant chmod +x command
+
+---
+
+### 3. Missing `.PHONY` declarations
+**Problem**: Without `.PHONY`, if files named `run`, `graph`, etc. existed, Make would skip those targets.
+
+**Solution**: Added `.PHONY: help it run profile explain graph clean` declaration.
+
+**Commit**: `e5ceeb2` - feat: add .PHONY declarations for all targets
+
+---
+
+### 4. No `clean` target
+**Problem**: No standard way to remove build artifacts.
+
+**Solution**: Added `clean` target to remove binary, output files, and profile directory:
+```makefile
+clean:
+	rm -f ${BINARY_NAME} program.out
+	rm -rf profile/
+```
+
+**Commit**: `7927df4` - feat: add clean target to remove build artifacts
+
+---
+
+### 5. Missing `help` or default target
+**Problem**: Running `make` with no arguments was unclear about available targets.
+
+**Solution**: Added `help` target documenting all available commands and their usage.
+
+**Commit**: `24fdc1c` - feat: add help target to document available commands
+
+---
+
+### 6. Profile directory not created
+**Problem**: The `profile` and `explain` targets wrote to `profile/cpu.prof` but never created the directory, causing failures on first run.
+
+**Solution**: Added `mkdir -p profile` to both `profile` and `explain` targets.
+
+**Commit**: `bb48d07` - fix: ensure profile directory exists before writing
+
+---
+
+### 7. No dependency check on `graph`
+**Problem**: The `graph` target assumed `profile/cpu.prof` exists but didn't depend on `profile`.
+
+**Solution**: Changed `graph:` to `graph: profile` to ensure profiling runs first.
+
+**Commit**: `3158c35` - fix: add profile dependency to graph target
+
+---
+
+### 8. Verbose command prefixes
+**Problem**: Every command used `@` prefix individually to suppress output, cluttering the file.
+
+**Solution**: Added `.SILENT:` directive at the top and removed all `@` prefixes. Also moved `TEST` variable to top with other variables.
+
+**Commit**: `8f70bfb` - refactor: use .SILENT directive instead of @ prefixes
+
+---
+
+## Additional Suggestions (Not Yet Implemented)
+
+### 9. Missing `lambda` binary in `.gitignore`
+**Issue**: The `.gitignore` has `*.exe` but not the actual `lambda` binary name. Since we removed the `.exe` extension, the binary won't be ignored.
+
+**Recommendation**: Add `lambda` to `.gitignore`:
+```
+# Build artifacts
+lambda
+```
+
+---
+
+### 10. No explicit default target
+**Issue**: While `help` is currently the first target (and thus default), it's not explicitly declared.
+
+**Recommendation**: Add `.DEFAULT_GOAL = help` at the top for clarity:
+```makefile
+BINARY_NAME=lambda
+TEST=simple
+
+.DEFAULT_GOAL := help
+.SILENT:
+.PHONY: help it run profile explain graph clean
+```
+
+---
+
+## Summary
+
+The Makefile has been significantly improved with better organization, proper dependency management, directory creation, helpful documentation, and cleaner syntax. The remaining suggestions are minor quality-of-life improvements that can be addressed as needed.