From f305e839de79c81e5ee8c720abb10289b37d2535 Mon Sep 17 00:00:00 2001
From: Daniel Lehrner <daniel@io.builders>
Date: Sun, 22 Aug 2021 23:36:41 +0200
Subject: [PATCH] added comment to the Makefile

Signed-off-by: Daniel Lehrner <daniel@io.builders>
---
 Makefile | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index c81f50d..e7daedb 100644
--- a/Makefile
+++ b/Makefile
@@ -38,6 +38,7 @@ endif
 .PHONY: clean
 .PHONY: test
 
+# libcrypto from OpenSSL will be renamed to this, to avoid naming conflicts
 CRYPTO_LIB=besu_native_ec_crypto
 CRYPTO_LIB_PATH=$(PATHL)lib$(CRYPTO_LIB).$(LIBRARY_EXTENSION)
 
@@ -46,10 +47,15 @@ BUILD_PATHS = $(PATHB) $(PATHO) $(PATHR) ${PATHL}
 SRCT = $(wildcard $(PATHT)*.c)
 
 COMPILE=gcc -c -Wall -Werror -std=c11 -O3 -fPIC
+
+# this is used in the tests to find the local copy of the crypto library
 LINK_TEST=gcc -L$(PATHL) -Wl,-rpath $(PATHL)
+# this is used for the  besu_native_ec library release. The crypto library will be in the same folder as it,
+# because they are shipped later in a jar file together
 LINK_RELEASE=gcc -L$(PATHL) -Wl,-rpath ./
 COMPILE_FLAGS=-I. -I$(PATHU) -I$(PATHS) -I$(PATH_OPENSSL_INCLUDE) -DTEST
 
+# the following commands are used to create the console output of the tests
 RESULTS = $(patsubst $(PATHT)test_%.c,$(PATHR)test_%.txt,$(SRCT) )
 
 PASSED = `grep -s PASS $(PATHR)*.txt`
@@ -67,24 +73,31 @@ test: $(BUILD_PATHS) $(RESULTS) $(CRYPTO_LIB_PATH)
 
 	./check_failing_test.sh
 
+# the result files are created by executing the tests and writing all their output into it
 $(PATHR)%.txt: $(PATHB)%.$(TEST_EXTENSION)
 	-./$< > $@ 2>&1
 
+# the sign test uses the verification and key recovery as well, therefore those are added to its dependencies
 $(PATHB)test_ec_sign.$(TEST_EXTENSION): $(CRYPTO_LIB_PATH) $(PATHO)test_ec_sign.o $(PATHO)ec_sign.o $(PATHO)ec_verify.o $(PATHO)ec_key_recovery.o $(PATHU)unity.o $(PATHO)constants.o $(PATHO)utils.o $(PATHO)ec_key.o
 	$(LINK_TEST) -Wl,-rpath $(PATHL) $(CFLAGS) -o $@ $^ -l$(CRYPTO_LIB) -lc
 
+# the other test don't have other dependencies and are compiled an their own
 $(PATHB)test_%.$(TEST_EXTENSION): $(CRYPTO_LIB_PATH) $(PATHO)test_%.o $(PATHO)%.o $(PATHU)unity.o $(PATHO)constants.o $(PATHO)utils.o $(PATHO)ec_key.o
 	$(LINK_TEST) -Wl,-rpath $(PATHL) $(CFLAGS) -o $@ $^ -l$(CRYPTO_LIB) -lc
 
+# creates the test object files from the test *.c files
 $(PATHO)%.o:: $(PATHT)%.c
 	$(COMPILE) --debug $(CFLAGS) $(COMPILE_FLAGS) $< -o $@
 
+# creates the object file from the *.c files in src/
 $(PATHO)%.o:: $(PATHS)%.c
 	$(COMPILE) --debug $(CFLAGS) $(COMPILE_FLAGS) $< -o $@
 
+# creates the object files from the unity (test framework) files
 $(PATHO)%.o:: $(PATHU)%.c $(PATHU)%.h
 	$(COMPILE) --debug $(CFLAGS) $(COMPILE_FLAGS) $< -o $@
 
+# the following commands create the directories of the build folder
 $(PATHB):
 	$(MKDIR) $(PATHB)
 
@@ -103,16 +116,26 @@ $(PATHRO):
 $(PATHL):
 	$(MKDIR) $(PATHL)
 
+# the crypto library from OpenSSL is copied and renamed
 $(CRYPTO_LIB_PATH): $(PATHL)
 	$(COPY) $(OPENSSL_LIB_CRYPTO) $@
+# renaming a shared library is not enough. It's name/path is part of the file itself and encoded within it.
+# For Linux it is enough to change the soname (id) to the new file name, as Linux will search in
+# various directories for it
 ifeq ($(shell uname -s),Linux)
 	patchelf --set-soname lib$(CRYPTO_LIB).$(LIBRARY_EXTENSION) $@
 endif
-
+# Mac OS will look for the library only in the path that is defined in id. We change it using the variable rpath at
+# the beginning and adding the file name afterwards. The value for rpath is defined in $LINK_TEST and $LINK_RELEASE
+# respectively, when the test and the besu_native library are linked
+#
+# More details about native library resolution on Mac OS can be found here:
+# https://medium.com/@donblas/fun-with-rpath-otool-and-install-name-tool-e3e41ae86172
 ifeq ($(shell uname -s),Darwin)
 	install_name_tool -id "@rpath/lib$(CRYPTO_LIB).$(LIBRARY_EXTENSION)" $@
 endif
 
+# the release build is created without debugging symbols and copied to the folder release/
 release_build: $(PATHRO)constants.o $(PATHRO)ec_key.o $(PATHRO)ec_key_recovery.o $(PATHRO)ec_sign.o $(PATHRO)ec_verify.o $(PATHRO)utils.o
 	$(COPY) $(CRYPTO_LIB_PATH) $(PATHRE)
 	$(LINK_RELEASE) -Wl,-rpath ./ $^ -l$(CRYPTO_LIB) -fPIC -shared $(CFLAGS) -o $(PATHRE)libbesu_native_ec.$(LIBRARY_EXTENSION)