diff --git a/README.md b/README.md index 3989029b00e00fec73eefd37e57216af42f2fa54..5941f5ab818317984bdf6161e078cb967ee0e5a9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[](https://git.ece.iastate.edu/danc/MicroCART/commits/master) +[](https://git.ece.iastate.edu/danc/MicroCART/commits/master) # MicroCART diff --git a/ci/README.md b/ci/README.md index 3a358d1ecc490882f7c11244c2a365e48b1d27dd..edd129cadf36d32a62065683ba34da5f479641da 100644 --- a/ci/README.md +++ b/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. diff --git a/quad/README.md b/quad/README.md index d1de70e5870154e88688645521e88680715e4f7a..c71d49fb42905f4e43bbb4d09a19e5de3004eaf0 100644 --- a/quad/README.md +++ b/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) diff --git a/quad/doc/Makefiles.md b/quad/doc/Makefiles.md new file mode 100644 index 0000000000000000000000000000000000000000..994c4d156b490bd0a11aadcbfbc87e2f7fd2aef3 --- /dev/null +++ b/quad/doc/Makefiles.md @@ -0,0 +1,46 @@ +# 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