Merge branch 'TESTING_documentation_updates' into 'master'

Add Makefile markdown for quad/

See merge request !30

README.md

-[![build status](https://git.ece.iastate.edu/danc/MicroCART/badges/master/build.svg)](https://git.ece.iastate.edu/danc/MicroCART/commits/master)
+[![pipeline status](https://git.ece.iastate.edu/danc/MicroCART/badges/master/pipeline.svg)](https://git.ece.iastate.edu/danc/MicroCART/commits/master)
 
 
 # MicroCART 

ci/README.md

@@ -9,4 +9,4 @@ It runs [make](quad/Makefile) under the quad directory to build the project.
 
 ## Test Stage
 The test stage is defined by the [`ci-test.sh`](ci/ci-test.sh) file.
-It runs [make test](quad/Makefile#36) under the quad directory to run the tests.
+It runs [make test](quad/Makefile#L36) under the quad directory to run the tests.

quad/README.md

@@ -65,6 +65,8 @@ cd src/<project> && make
 **NOTE**: All build artifacts will be placed in `lib` or `bin` (depending on
 whether it is a library or executable, respectively)
 
+To learn more about the makefiles, see [Makefiles.md](doc/Makefiles.md)
+
 ## Testing
 
 #### Automated Tests
@@ -92,10 +94,11 @@ Ideally, you would run these tests from the XSDK IDE.
 * [The Quad Application](src/quad_app/README.md)  
 * [Quad App on the Zybo (Real Quad)](xsdk_workspace/real_quad/README.md)  
 * [Quad App on Unix (Virtual Quad)](src/virt_quad/README.md)  
-* [XSDK Instructions](xsdk_workspace/README.md)  
+* [XSDK Instructions](xsdk_workspace/README.md)
 
 ## Other Documents
 * [Hardware Block Diagram](doc/images/FPGA_Diagram.png)
-* [Zybo Pinout Assignments](doc/zybo_pinout_assignments.md)  
-* [How to use Xilinx software tools](doc/how_to_use_XSDK.md)
+* [Zybo Pinout Assignments](doc/zybo_pinout_assignments.md)
+* [How to use Xilinx software tools](doc/how_to_use_XSDK.md)  
+* [How to use the makefile structure](doc/Makefiles.md)
 * [Unity notes](doc/Unity_notes.md)

quad/doc/Makefiles.md

+#  How to use the makefiles
+## [library.mk](../library.mk)
+This file contains many definitions of make targets for building libraries and building and running their corresponding tests.
+A set of variable definitions are at the top of the file.
+Within this file, the "User Targets" are defined for building a library (`default`),
+building and running tests (`test`), and cleaning the library (`clean`).
+The "Internal Targets" are used for building the library and test binary and rely on abstraction.
+
+## [executable.mk](../executable.mk)
+This file contains definitions of make targets for building executables.
+Similar to `library.mk`, this file has a set of variable definitions at the top of the file.
+The "User Targets" are defined for building the executable and cleaning.
+The "Internal Targets" are used for building the executable and rely on abstraction.
+
+## [quad/Makefile](../Makefile)
+This Makefile contains targets for building libraries and binaries and their associated tests.
+In this file, the specific libraries/executables and their locations are listed,
+as opposed to the `.mk` files which have purely abstract definitions.
+It also contains a `clean` target for removing compiled libraries and binaries.
+A target for generating an image of the control network, called `diagram`, is also located here.
+
+## Library Makefile
+Each library needs its own Makefile.
+This contains a set of definitions for variables, so that the abstract targets in `library.mk`
+can work properly, and any additional targets you want to add that are specific to this library.
+
+The following variable definitions should be included:
+- `NAME`: The name of the library
+- `TOP`: a relative path to the `quad/` directory
+- `REQLIBS`: a list of the libraries necessary to compile this library, in the form of compiler flags, i.e. `-l<name>`
+
+_Note: The `REQLIBS` list should include the name of this library at a minimum,
+as any tests associated with it would need its own library to be linked in order to be useful._
+
+Additionally, a line like the following should be included:
+
+`include $(TOP)/library.mk`
+
+This allows the library to use the targets in the `library.mk` file to be applied to this directory.
+Any other make targets wanted for the library should also be included.
+
+## How to add a library
+To add a library:
+1. Add your library to the `libs` and `clean` targets in [`quad/Makefile`](../Makefile) with a path to the directory containing the library
+1. Add a Makefile to the new library with the variable definitions in it as described above
+1. Update the `REQLIBS` variable for any library or executable that needs this new library to compile