From f94c5286a121437f3bf880068d3770e6e92cfa3e Mon Sep 17 00:00:00 2001
From: Paul McCarthy <pauldmccarthy@gmail.com>
Date: Fri, 19 Nov 2021 15:13:08 +0000
Subject: [PATCH] DOC: Readme - examples for compilation commands, and example
makefiles
---
README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 69 insertions(+)
diff --git a/README.md b/README.md
index 92ebb8a..b24e8fc 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,57 @@ behaviour of various aspects of the `base` project. All tests are written
in Python, and are executed with `pytest`.
+## Standard conventions for C/C++/CUDA projects.
+
+Commands for compilation of intermediate object files should have the
+form:
+
+ $(CC) $(CFLAGS) <input/output files> # for .c files
+ $(CXX) $(CXXFLAGS) <input/output files> # for .cc files
+ $(CXX) $(CUDACXXFLAGS) <input/output files> # for .cc files which are to
+ # be linked into CUDA
+ # libraries/executables
+ $(NVCC) $(NVCCFLAGS) <input/output files> # for .cu files
+
+And commands for compilation and linking of executables and libraries
+should have the form:
+
+ $(CC) $(CFLAGS) <input/output files> ${LDFLAGS} # for c libs/exes
+ $(CXX) $(CXXFLAGS) <input/output files> ${LDFLAGS} # for c++ exes
+ $(CXX) $(CXXFLAGS) -shared <input/output files> ${LDFLAGS} # for c++ libs
+ $(NVCC) $(NVCCFLAGS) -shared <input/output files> ${NVCCLDFLAGS} # for CUDA libs
+ $(NVCC) $(NVCCFLAGS) <input/output files> ${NVCCLDFLAGS} # for CUDA exes
+
+
+`LDFLAGS` *must* come at the end, to ensure proper linking.
+
+An example C++ `Makefile` might look like this:
+
+```
+include ${FSLCONFDIR}/default.mk
+
+PROJNAME = myproject
+SOFILES = libmylib.so
+XFILES = myexe1 myexe2
+
+# Instead of explicitly defining this rule,
+# We could instead rely on implicit Make
+# rules for generating *.o files from *.cc
+# files.
+%.o: %.cc
+ $(CXX) $(CXXFLAGS) -c -o $@ $<
+
+libmylib.so: myobj1.o myobj2.o
+ $(CXX) $(CXXFLAGS) -shared -o $@ $^ $(LDFLAGS)
+
+myexe1: myexe1.o myobj1.o
+ $(CXX) $(CXXFLAGS) -o $@ $^ $(LDFLAGS)
+
+myexe2: myexe2.o myobj2.o
+ $(CXX) $(CXXFLAGS) -o $@ $^ $(LDFLAGS)
+```
+
+
## Building FSL CUDA projects.
Some FSL projects (e.g. [`fsl/eddy`(https://git.fmrib.ox.ac.uk/fsl/eddy) use
@@ -42,3 +93,21 @@ using static linking:
The `Makefile` for each FSL CUDA project may provide additional options for
controlling compilation.
+
+An example `Makefile` for a C++/CUDA project might look like this:
+
+```
+include ${FSLCONFDIR}/default.mk
+
+PROJNAME = myproject
+XFILES = myexe
+
+%.o: %.cu
+ $(NVCC) $(NVCCFLAGS) -c -o $@ $<
+
+%.o: %.cc
+ $(CXX) $(CUDACXXFLAGS) -c -o $@ $<
+
+myexe:
+ $(NVCC) $(NVCCFLAGS) -o $@ $< $(NVCCLDFLAGS)
+```
--
GitLab