OuNuPo/HELP-makefile.md

# Makefile Documentation

## SYNTAX: AUTOMATIC VARIABLES
https://www.gnu.org/software/make/manual/html_node/Automatic-Variables.html

* $@  file name of the target of the rule.
* $<  name of the first prerequisite.
* $?  names of all the prerequisites that are newer than the target, with spaces between .
* $^  names of all the prerequisites,
* $(@D)  directory part of the file name of the target,

## SYNTAX: PRINTING / ERRORS
@ preceeding command tells make not to print the command being executed
- preceeding a command tells make to ignore errors in a recipe line


## DEPENDENCIES AND RULES
a rule "asks" a  *dependency* to be executed, only if the depency does not exist as a file
i.e. I have the 2 following rules in my make file:

```
list.txt:
	ls . -1 > $@

tts: list.txt
	cat $< | espeak
```
when i run: `make tts`
tts rule will execute its dependency list.txt  IF the list.xt does not exist in the top level of working directory. ELSE it will execute the list.txt


## TARGET NAMES
**use as rules' targets (first line of a rule,left of :) the name of resulting file(s)**

One main problem in the OuNuPo makefile is the execution of the tesseract rule, every time another rule requests it (in make lingo has it as a dependency). This a duplication of the same process (ocr), which takes quite some time, and hence we want to avoid repeting, if the scanned images haven't changed.
Make has a very simple way of **avoiding this duplication of a process/rule**.
It is done **carefully defining the rules' target** - the name given to the rule, by which we invoke in order to execute that rule.
By having **the target of a rule take the name of the file(s), which will result from to the rule's execution**, the Makefile, will **check if that file is "out of date"**.
"A target is out of date if it does not exist or if it is older than any of the prerequisites "

If the target/resulting file(s) are **not present**, the dependency rule will be executed
If the target/resulting file(s) are **not present**,  the dependency rule will NOT be executed

what follows is a simple example
```
foo.txt:
	echo "this is a test" >> foo.txt
	@echo "$@ was made"

art: foo.txt
	cat foo.txt | figlet
	@echo "$@ was made"
```
For the first time you run `make art` the foo.txt dependency rule will be executed
In subsequent runs of  `make art`  foo.txt dependency rule will NOT be executed, because its target: foo.txt is already in the make working directory
To trigger the execution of foo.txt rule, we need to remove its target from the working directoy
That task if often delegate to a rule with target `clean` which removes the files/targets of make, such as

```
clean: removes output (target) files
	rm ocr/output.txt
	rm $(wildcard output/*)
	rm $(tmpfile)
```

After running `make clean` the foo.txt rule is executed (as a dependancy) when running `make art`

Targets can also include subfolders:

```
output/art.txt: foo.txt
	cat foo.txt | figlet > $@
	@echo "$@ was made"
```
which can be invoked by `make output/art.txt`

Read more on https://www.gnu.org/software/make/manual/html_node/Rule-Syntax.html#Rule-Syntax

# LINKS
* About Makefile syntax: [5 Writing Recipes in Rules](https://www.gnu.org/software/make/manual/make.html#Recipes)