DOC: Readme - examples for compilation commands, and example makefiles

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)
+```