add a few comments

firmware/bundle.mk

@@ -1,17 +1,24 @@
+# Use SHORT_BOARD_NAME for BUNDLE_NAME if it's empty.
+# BUNDLE_NAME is usually more specific - it points to a variant of a board.
 ifeq (,$(BUNDLE_NAME))
   BUNDLE_NAME = $(SHORT_BOARD_NAME)
 endif
 
+# If we're running on Windows, we need to call the .exe of hex2dfu
 ifneq (,$(findstring NT,$(UNAME_S)))
 	H2D = ../misc/encedo_hex2dfu/hex2dfu.exe
 else
 	H2D = ../misc/encedo_hex2dfu/hex2dfu.bin
 endif
 
+# DFU and DBIN are uploaded as artifacts, so it's easier to have them in the deliver/ directory
+#  than to try uploading them from the rusefi.snapshot.<BUNDLE_NAME> directory
 DFU = $(DELIVER)/$(PROJECT).dfu
 DBIN = $(DELIVER)/$(PROJECT).bin
 OUTBIN = $(FOLDER)/$(PROJECT).bin
 
+# If provided with a git reference and the LTS flag, use a folder name including the ref
+# This weird if statement structure is because Make doesn't have &&
 ifeq ($(LTS),true)
 ifneq (,$(REF))
   FOLDER = rusefi.$(REF).$(BUNDLE_NAME)
@@ -36,10 +43,12 @@ UPDATE_FOLDER_SOURCES = \
   $(INI_FILE) \
   ../misc/console_launcher/readme.html
 #  ../misc/console_launcher/rusefi_updater.exe
+# Uncomment and put a backslash after readme.html to put rusefi_updater.exe in the bundle
 
 FOLDER_SOURCES = \
   ../java_console/bin
 
+# Custom board builds don't include the simulator
 ifneq ($(BUNDLE_SIMULATOR),no)
   SIMULATOR_OUT = ../simulator/build/rusefi_simulator.exe
 endif
@@ -67,6 +76,7 @@ CACERTS_FOLDER_SOURCES = $(wildcard ../misc/console_launcher/update-ts-cacerts/*
 BOOTLOADER_BIN = bootloader/blbuild/openblt_$(PROJECT_BOARD).bin
 BOOTLOADER_HEX = bootloader/blbuild/openblt_$(PROJECT_BOARD).hex
 
+# We need to put different things in the bundle depending on some meta-info flags
 ifeq ($(USE_OPENBLT),yes)
   BOOTLOADER_OUT = $(BOOTLOADER_HEX)
   BOUTS = $(FOLDER)/openblt.bin
@@ -81,6 +91,9 @@ endif
 
 ST_DRIVERS = $(DRIVERS_FOLDER)/silent_st_drivers2.exe
 
+# We're kinda doing things backwards from the normal Make way.
+# We're listing some files we want to get copied from the bundle,
+# and these commands turn them into their destination path within the bundle.
 UPDATE_FOLDER_TARGETS = $(addprefix $(FOLDER)/,$(notdir $(UPDATE_FOLDER_SOURCES)))
 UPDATE_CONSOLE_FOLDER_TARGETS = $(addprefix $(CONSOLE_FOLDER)/,$(notdir $(UPDATE_CONSOLE_FOLDER_SOURCES)))
 CACERTS_FOLDER_TARGETS = $(addprefix $(CACERTS_FOLDER)/,$(notdir $(CACERTS_FOLDER_SOURCES)))
@@ -108,6 +121,8 @@ $(SIMULATOR_OUT):
 
 $(BOOTLOADER_HEX) $(BOOTLOADER_BIN): .bootloader-sentinel ;
 
+# We pass SUBMAKE=yes to the bootloader Make instance so it knows not to try to build configs,
+#  as that would result in two simultaneous config generations, which causes issues.
 .bootloader-sentinel: $(CONFIG_FILES)
 	BOARD_DIR=../$(BOARD_DIR) BOARD_META_PATH=../$(BOARD_META_PATH) $(MAKE) -C bootloader -r SUBMAKE=yes
 	@touch $@
@@ -126,6 +141,8 @@ $(BOUTS): $(FOLDER)/openblt%: bootloader/blbuild/openblt_$(PROJECT_BOARD)% | $(F
 $(OUTBIN) $(FOLDER)/$(PROJECT).dfu: $(FOLDER)/%: $(DELIVER)/% | $(FOLDER)
 	ln -rfs $< $@
 
+# The DFU is currenly not included in the bundle, so these prerequisites are listed as order-only to avoid building it.
+# If you want it, you can build it with `make rusefi.snapshot.$BUNDLE_NAME/rusefi.dfu`
 $(DFU) $(DBIN): .h2d-sentinel ;
 
 .h2d-sentinel: $(BUILDDIR)/$(PROJECT).hex $(BOOTLOADER_OUT) $(BINSRC) | $(DELIVER)
@@ -146,6 +163,7 @@ $(DELIVER) $(ARTIFACTS) $(FOLDER) $(CONSOLE_FOLDER) $(DRIVERS_FOLDER) $(CACERTS_
 $(ARTIFACTS)/$(BUNDLE_FULL_NAME).zip: $(BUNDLE_FILES) | $(ARTIFACTS)
 	zip -r $@ $(BUNDLE_FILES)
 
+# The autopdate zip doesn't have a folder with the bundle contents
 $(ARTIFACTS)/$(BUNDLE_FULL_NAME)_autoupdate.zip: $(UPDATE_BUNDLE_FILES) | $(ARTIFACTS)
 	cd $(FOLDER) &&	zip -r ../$@ $(subst $(FOLDER)/,,$(UPDATE_BUNDLE_FILES))
 
@@ -160,6 +178,7 @@ CLEAN_BUNDLE_HOOK:
 	rm -rf $(FOLDER)
 	@echo Done Cleaning Bundle
 
+# We need to use secondary expansion on these rules to find the target file in the source file list.
 PERCENT = %
 
 .SECONDEXPANSION:

firmware/rusefi_config.mk

@@ -1,5 +1,6 @@
 include $(PROJECT_DIR)/../java_tools/java_tools.mk
 
+# We're assuming that META_OUTPUT_ROOT_FOLDER is a path relative to PROJECT_DIR
 INI_FILE = $(PROJECT_DIR)/$(META_OUTPUT_ROOT_FOLDER)tunerstudio/generated/rusefi_$(SHORT_BOARD_NAME).ini
 SIG_FILE = $(PROJECT_DIR)/tunerstudio/generated/signature_$(SHORT_BOARD_NAME).txt
 
@@ -31,16 +32,32 @@ CONFIG_FILES = \
 
 .FORCE:
 
+# This is necessary because the ChibiOS makefile builds a .o file and generates
+#  the deps for that .o file in the same GCC call, so if the .deps aren't already
+#  in the correct state, things can fail to build because Make doesn't know it needs
+#  to build the prerequisites (in this case CONFIG_FILES and RAMDISK) for those files ahead of time.
 $(TCOBJS): $(CONFIG_FILES)
 $(TCPPOBJS): $(RAMDISK)
 
+# Always try to rebuild the signature file.
+# The script won't actually update the file if the signature hasn't changed, so it won't trigger a config file generation.
 $(SIG_FILE): .FORCE
 	bash $(PROJECT_DIR)/gen_signature.sh $(SHORT_BOARD_NAME)
 
+# This sentinel's purpose is to trigger rebuilds when building for a different target.
+# SHORT_BOARD_NAME doesn't cover all possible changes.
+# For example, if I build Proteus F7, then build Proteus F7 Debug, it won't actually rebuild,
+#  because SHORT_BOARD_NAME hasn't changed. BUNDLE_NAME would be a better specifier,
+#  but it's currently only available from the build_firmware GHA workflow.
+#  Another option would be to use BOARD_META_PATH, and export it in config.sh.
 .target-sentinel: .FORCE
 	if [ "$$(cat $@ 2>/dev/null)" != $(SHORT_BOARD_NAME) ]; then \
 	echo $(SHORT_BOARD_NAME) >$@; fi
 
+# Most sentinels are used for multiple targets that are created with a single recipe.
+# In newer versions of GNU Make this is done using the &: operator,
+#  but for supporting older versions, we do it this way.
+# In particular, the version that ships with macOS is quite old.
 $(RAMDISK): .ramdisk-sentinel ;
 
 .ramdisk-sentinel: $(INI_FILE) .target-sentinel
@@ -49,6 +66,8 @@ $(RAMDISK): .ramdisk-sentinel ;
 
 $(CONFIG_FILES): .config-sentinel ;
 
+# CONFIG_DEFINITION is always rebuilt, but the file will only be updated if it needs to be,
+# so it won't trigger a config file generation unless it needs to.
 .config-sentinel: $(CONFIG_INPUTS) $(CONFIG_DEFINITION) .target-sentinel
 ifneq (,$(CUSTOM_GEN_CONFIG))
 	bash $(BOARD_DIR)/$(CUSTOM_GEN_CONFIG)

firmware/rusefi_pch.mk

@@ -15,6 +15,10 @@ else
 endif
 
 # Make all cpp objects explicitly depend on the PCH
+# This is necessary because the ChibiOS makefile builds a .o file and generates
+#  the deps for that .o file in the same GCC call, so if the .deps aren't already
+#  in the correct state, things can fail to build because Make doesn't know it needs
+#  to build the prerequisites (in this case PCHOBJ) for those files ahead of time.
 $(TCPPOBJS) : $(PCHOBJ)
 $(ACPPOBJS) : $(PCHOBJ)
 

java_tools/java_tools.mk

@@ -1,9 +1,12 @@
 JAVA_TOOLS = $(PROJECT_DIR)/../java_tools
 
-#
+# We run multiple processes in parallel by passing the -j option to Make.
-# problem statement: 'make -j4' could easily attempt to run parallel gradle processes. gradle does not seem to like it
+# If multiple recipes call Gradle, it is likely that those recipes will be executed in parallel.
-# see notes at https://github.com/rusefi/rusefi/pull/6031
+# Gradle jobs do not like being run in parallel; it causes all kinds of nonsense errors.
-#
+# To solve this, we use flock. Flock checks if a file is locked. If it is, it waits until it isn't.
+# Once it isn't locked, it locks it, runs the command, then unlocks it once the command is finished.
+# Note that flock doesn't ship on macOS. You can install it with `brew install flock`
+# On Windows, flock comes with Cygwin.
 FLOCK = flock /tmp/java.lock
 
 FIELDS =   $(PROJECT_DIR)/../java_console/models/src/main/java/com/rusefi/config/generated/Fields.java
@@ -11,9 +14,12 @@ FIELDS =   $(PROJECT_DIR)/../java_console/models/src/main/java/com/rusefi/config
 CONFIG_DEFINITION = $(JAVA_TOOLS)/configuration_definition/build/libs/config_definition-all.jar
 CONFIG_DEFINITION_BASE = $(JAVA_TOOLS)/configuration_definition_base/build/libs/config_definition_base-all.jar
 ENUM_TO_STRING = $(JAVA_TOOLS)/enum_to_string/build/libs/enum_to_string-all.jar
-CONSOLE_OUT = ../java_console_binary/rusefi_console.jar
+CONSOLE_OUT = $(JAVA_TOOLS)../java_console_binary/rusefi_console.jar
-AUTOUPDATE_OUT = ../java_console_binary/rusefi_autoupdate.jar
+AUTOUPDATE_OUT = $(JAVA_TOOLS)../java_console_binary/rusefi_autoupdate.jar
-TPL_OUT = ../java_tools/ts_plugin_launcher/build/jar/rusefi_ts_plugin_launcher.jar
+TPL_OUT = $(JAVA_TOOLS)../java_tools/ts_plugin_launcher/build/jar/rusefi_ts_plugin_launcher.jar
+
+# We use .FORCE to always rebuild these tools. Gradle won't actually touch the jars if it doesn't need to,
+# so we don't have to worry about triggering rebuilds of things that have these tools as a prerequisite.
 
 $(CONFIG_DEFINITION): .FORCE
 	cd $(JAVA_TOOLS) && $(FLOCK) ./gradlew :config_definition:shadowJar
@@ -27,6 +33,7 @@ $(ENUM_TO_STRING): .FORCE
 $(TPL_OUT): .FORCE
 	cd ../java_tools && $(FLOCK) ./gradlew :ts_plugin_launcher:shadowJar
 
+# The console depends on Fields.java.
 $(CONSOLE_OUT): $(FIELDS) .FORCE
 	cd ../java_tools && $(FLOCK) ./gradlew :ui:shadowJar