From c579dd014e8a799dc2a30faaf7242c8f7ad9fa1c Mon Sep 17 00:00:00 2001
From: Simon Rose <simon.rose@ess.eu>
Date: Wed, 16 Sep 2020 15:30:45 +0200
Subject: [PATCH] Some cleanup and clarification
---
docs/driver.makefile.md | 32 +++++++++++++++++++++++---------
1 file changed, 23 insertions(+), 9 deletions(-)
diff --git a/docs/driver.makefile.md b/docs/driver.makefile.md
index 61b9082b..85299de0 100644
--- a/docs/driver.makefile.md
+++ b/docs/driver.makefile.md
@@ -37,7 +37,9 @@ The key is in how `make` generates its dependency tree. Unlike many programming
<!-- Perhaps we can expand this more, but I will leave it like this for now. -->
-## Stage 1 of the build process: The e3-wrapper
+## The `make` process for E3
+
+### Stage 1 of the build process: The e3-wrapper
We start in the e3-wrapper directory, and run (for example) `make build`. The first thing that happens is that
we load the makefiles from the configure directory; these in turn load `CONFIG_MODULE` and `RELEASE` which specify
@@ -57,7 +59,7 @@ module directory, and run a `git checkout` command to make sure that the module
`$(E3_MODULE_MAKE_CMDS)` is defined in `CONFIG_E3_MAKEFILE` which specifies which arguments should be passed
to this recursive call of `make`.
-## Stage 2: Defining `EPICSVERSION`
+### Stage 2: Defining `EPICSVERSION`
The first pass through is to determine the EPICS version that we are building for. In E3, we build for one
version at a time; this is taken from `EPICS_LOCATION`:
@@ -76,7 +78,7 @@ next stage of the build process once with `EPICSVERSION=7.0.4`.
Note that `build`, `install`, and `debug` all use the same recurisve call to `make`.
-## Stage 3: Defining `T_A`
+### Stage 3: Defining `T_A`
Now that we know which version of EPICS to build for, we go on to determine the target architectures to build for.
In this case, we may build for more than one architecture at a time; at the moment, ESS supports `linux-x86_64` and
@@ -112,7 +114,7 @@ install build debug::
done
```
-## Stage 4: Preparing to build `T_A`
+### Stage 4: Preparing to build `T_A`
For this stage of the build process, we are still in the module directory; the next stages will be done in the
directories `O.$(EPICSVERSION)_Common` or `O.$(EPICSVERSION)_$(T_A)`, respectively. These directories will also be
@@ -150,7 +152,7 @@ install build debug:: O.${EPICSVERSION}_Common O.${EPICSVERSION}_${T_A}
Note that due to the argument `-C O.${EPICSVERSION}_${T_A}` we switch to that directory, using the same
`${USERMAKEFILE}` to manage the build process.
-## Stage 5: Building `T_A`
+### Stage 5: Building `T_A`
We have now collected the majority of the information that we need to build our module. We will do a little more
organization and preparation, and then the process will be handed over to the EPICS build system. Note that this
@@ -159,7 +161,14 @@ part of `driver.makefile` is by far the most complicated section, and takes some
To begin with, I would like to point out a couple sections of interest, followed by tracing through what happens
when you include a line such as `SOURCES += file.c` in your `$(module).Makefile`.
-### Points of interest
+## Points of interest
+
+
+
+## Examples of the `make` process
+
+We will provide a few examples of how `make` processes the data and produces the desired result. The first is
+installing a header file, and the second is actually compiling a source file.
### Installing a header file
@@ -260,9 +269,14 @@ The next steps are complicated due to being shared among different configure fil
$(LOADABLE_SHRLIBNAME): $(LIBRARY_OBJS) $(LIBRARY_RESS) $(SHRLIB_DEPLIBS)
$(LOADABLE_SHRLIBNAME): $(LOADABLE_SHRLIB_PREFIX)%$(LOADABLE_SHRLIB_SUFFIX):
- @$(RM) $@
- $(LINK.shrlib)
- $(MT_DLL_COMMAND)
+ @$(RM) $@
+ $(LINK.shrlib)
+ $(MT_DLL_COMMAND)
+ ```
+ where the linking command is provided in `CONFIG.Common.UnixCommon`:
+ ```makefile
+ LINK.shrlib = $(CCC) -o $@ $(TARGET_LIB_LDFLAGS) $(SHRLIBDIR_LDFLAGS) $(LDFLAGS)
+ LINK.shrlib += $(LIB_LDFLAGS) $(LIBRARY_LD_OBJS) $(LIBRARY_LD_RESS) $(SHRLIB_LDLIBS)
```
8. Last but not least, we need to connect this to the target `build`. In `RULES_BUILD` we find:
```makefile
--
GitLab