Make Concepts: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
No edit summary
 
(40 intermediate revisions by the same user not shown)
Line 1: Line 1:
=External=
* https://www.gnu.org/software/make/
=Internal=
=Internal=
* [[Make#Subjects|make]]
* [[Make#Subjects|make]]
=<tt>make</tt> Command Line=
<code>make</code> will interpret the command line tokens as: targets, definitions and execution flags (options). The arguments not recognized as definitions or execution flags are automatically interpreted as targets.
Anything that starts with "--" is an option, and it has to be known to <code>make</code> to be accepted.
<font color=darkkhaki>TODO: https://askubuntu.com/a/1448109</font>
=Rule=
{{External|https://www.gnu.org/software/make/manual/make.html#Rules}}
A makefile consists of rules with the following syntax:
<syntaxhighlight lang='make'>
target ...: prerequisites
    recipe
</syntaxhighlight>
A target can be either the name of a file that is generated by the recipe, or the name of an action to carry out. These are phony named [[#.PHONY|phony targets]], because they are not files.
A prerequisite is a file that is used as input to create the target. A target often depends on several files.
A recipe is an action that "make" carries out. A recipe may have more than one command, either on the same line or each on its own line. You need to put a tab character at the beginning of every recipe line. <font color=darkkhaki>Is this still true?</font> Usually the recipe (re-)creates the target file if any of the prerequisites change. However, the rule that specifies a recipe for the target need not have prerequisites.
==<tt>make</tt> Executes only the First Rule By Default==
{{External|https://www.gnu.org/software/make/manual/html_node/How-Make-Works.html}}
If not told otherwise, <code>make</code> will build the first target, along its prerequisites, then stop. If more than one files need to be generate, group them under common target, and put it in the first position in the file, or use <code>[[#.DEFAULT_GOAL|.DEFAULT_GOAL]]</code>.
<syntaxhighlight lang='make'>
.PHONY: generate_oapi_artifacts
generate_oapi_artifacts: spec.gen.go types.gen.go
spec.gen.go: ./petstore.yaml
oapi-codegen -generate spec -package petstore $< > $@
types.gen.go: ./petstore.yaml
oapi-codegen -generate types -package petstore $< > $@
</syntaxhighlight>
=Recipe=
{{External|https://www.gnu.org/software/make/manual/make.html#Recipes}}
==Recipe Echo==
{{External|https://www.gnu.org/software/make/manual/make.html#Echoing}}
By default, <code>make</code> prints each line of the recipe before it is executed.
When a line starts with "@", the echoing is supressed.
<syntaxhighlight lang='make'>
experiment:
@echo ${COLOR}
</syntaxhighlight>
==Recipes Preprocessing==
<code>make</code> pre-processes the recipe line before sending it to a shell (each line is [[#B013|sent to a different shell]]).
Preprocessing:
* Because dollar signs are used to start make variable references, if you really want a dollar sign in a target or prerequisite you must write two of them, '$$'. If you have enabled secondary expansion and you want a literal dollar sign in the prerequisites list, you must actually write four dollar signs ('$$$$').
==<span id="B013"></span>Recipes and Executing Shells==
<code>make</code> starts new sub shell for each line of the recipe.
==Setting Environment Variables for Recipe Commands==
Write all the environment variables you want to set in the environment of the recipe command in a file, possibly with another target:
Source the file '''on the same line''' as the command you want to provide environment variables to (this is because <code>make</code> [[#Recipes_and_Executing_Shells|starts a sub-shell]] for each [[#Recipe|recipe]] line.
<syntaxhighlight lang='make'>
pre-experiment:
echo "COLOR=FUCHSIA" > $(CURDIR)/build/.env
experiment: pre-experiment
. $(CURDIR)/build/.env; report-color
</syntaxhighlight>
To specify an environment variable verbatim in a recipe, you will need to use <code>$$</code> to prevent <code>make</code> from doing its own variable substitution. Also, because different lines are executed by different shells, the definition of the variable and the use of the variable must be on the same line.
<syntaxhighlight lang='make'>
some-target:
  COLOR="red"; echo "$${COLOR}"
</syntaxhighlight>


=<tt>.PHONY</tt>=
=<tt>.PHONY</tt>=
{{External|https://www.gnu.org/software/make/manual/make.html#Phony-Targets}}


By default, <code>make</code> targets are assumed to be files on disk. They will be built from other files as result of executing <code>make</code> with that name as argument. However, sometimes you want <code>make</code> to run commands that do not represent physical files in the filesystem, and if there's a file with the same name in the filesystem, <code>make</code> will be confused and will pick up the file. To avoid this, you can disambiguate with <code>.PHONY</code>:
By default, <code>make</code> targets are assumed to be files on disk. They will be built from other files as result of executing <code>make</code> with that name as argument. However, sometimes you want <code>make</code> to run commands that do not represent physical files in the filesystem, and if there's a file with the same name in the filesystem, <code>make</code> will be confused and will pick up the file. To avoid this, you can disambiguate with <code>.PHONY</code>:
Line 15: Line 94:
</syntaxhighlight>
</syntaxhighlight>


=<tt>.DEFAULT_GOAL</tt>=
{{External|https://www.gnu.org/software/make/manual/html_node/Special-Variables.html#index-_002eDEFAULT_005fGOAL-_0028define-default-goal_0029}}
<syntaxhighlight lang='make'>
.DEFAULT_GOAL := some_target
</syntaxhighlight>


=Variables=
=Variables=
Line 27: Line 111:
===<tt>$@</tt>===
===<tt>$@</tt>===
The file name of the target of the rule. In a pattern rule that has multiple targets <code>$@</code> is the name of whichever target caused the rule’s recipe to be run.
The file name of the target of the rule. In a pattern rule that has multiple targets <code>$@</code> is the name of whichever target caused the rule’s recipe to be run.
===<tt>$<</tt>===
The name of the first prerequisite. For this rule:
<syntaxhighlight lang='make'>
types.gen.go: petstore.yaml
oapi-codegen -generate types -package petstore $< > $@
</syntaxhighlight>
<code>$<</code> contains "petstore.yaml"
==Custom Variables==
{{External|https://www.gnu.org/software/make/manual/make.html#Using-Variables}}
Variables allow a text string to be defined once and substituted in multiple places later. A variable is a name defined in Makefile to represent a string of text, called the variable's value. These value are substituted in targets, prerequisites and other parts of the make file. A variable name may be any sequence of characters not containing ":", "#", "=", or whitespace.  Variable names beginning with "." and an uppercase letter may be given special meaning in future versions of make. Variable names are case sensitive. It is traditional to use upper case letters in variable names, but we recommend using lower case letters for variable names that serve internal purposes in the makefile, and reserving upper case for parameters that control implicit rules or for parameters that the user should override with command options.
This is how a variable is declared:
<syntaxhighlight lang='make'>
my_var = something
</syntaxhighlight>
This is how a variable is used:
<syntaxhighlight lang='make'>
prog.o: $(my_var)
</syntaxhighlight>
Variables can be used in the value of other variables:
<syntaxhighlight lang='make'>
my_var = something
my_other_var = ./$(my_var)/other
</syntaxhighlight>
===Initializing a Custom Variable with the Result of a Command Execution===
Use the <code>[[#shell_Function|shell]]</code> function:
<syntaxhighlight lang='make'>
some_var = $(shell $(CURDIR)/scripts/some-script.sh)
</syntaxhighlight>
=Functions=
==<tt>shell</tt> Function==
{{External|https://www.gnu.org/software/make/manual/make.html#Shell-Function}}
The <code>shell</code> function does command expansion: it takes as an argument a shell command and executes the command, expanding it to the output of the the command:
<syntaxhighlight lang='make'>
test: build
env MY_PRIVATE_KEY=$(shell ./scripts/get-my-private-key) go test ./...
</syntaxhighlight>
The <code>shell</code> function removes the trailing new lines and replaces the intermediate new lines with spaces.
=<tt>!=</tt> Shell Assignment Operator=
{{External|https://www.gnu.org/software/make/manual/make.html#Setting}}
The <code>!=</code> shell assignment operator is similar to the [[#shell_Function|<code>shell</code> function]]. It removes the trailing new lines and replaces the intermediate new lines with spaces.

Latest revision as of 23:03, 13 March 2024

Internal

make Command Line

make will interpret the command line tokens as: targets, definitions and execution flags (options). The arguments not recognized as definitions or execution flags are automatically interpreted as targets.

Anything that starts with "--" is an option, and it has to be known to make to be accepted.

TODO: https://askubuntu.com/a/1448109

Rule

https://www.gnu.org/software/make/manual/make.html#Rules

A makefile consists of rules with the following syntax:

target ...: prerequisites
    recipe

A target can be either the name of a file that is generated by the recipe, or the name of an action to carry out. These are phony named phony targets, because they are not files.

A prerequisite is a file that is used as input to create the target. A target often depends on several files.

A recipe is an action that "make" carries out. A recipe may have more than one command, either on the same line or each on its own line. You need to put a tab character at the beginning of every recipe line. Is this still true? Usually the recipe (re-)creates the target file if any of the prerequisites change. However, the rule that specifies a recipe for the target need not have prerequisites.

make Executes only the First Rule By Default

https://www.gnu.org/software/make/manual/html_node/How-Make-Works.html

If not told otherwise, make will build the first target, along its prerequisites, then stop. If more than one files need to be generate, group them under common target, and put it in the first position in the file, or use .DEFAULT_GOAL.

.PHONY: generate_oapi_artifacts

generate_oapi_artifacts: spec.gen.go types.gen.go

spec.gen.go: ./petstore.yaml
	oapi-codegen -generate spec -package petstore $< > $@

types.gen.go: ./petstore.yaml
	oapi-codegen -generate types -package petstore $< > $@

Recipe

https://www.gnu.org/software/make/manual/make.html#Recipes

Recipe Echo

https://www.gnu.org/software/make/manual/make.html#Echoing

By default, make prints each line of the recipe before it is executed.

When a line starts with "@", the echoing is supressed.

experiment:
	@echo ${COLOR}


Recipes Preprocessing

make pre-processes the recipe line before sending it to a shell (each line is sent to a different shell).

Preprocessing:

  • Because dollar signs are used to start make variable references, if you really want a dollar sign in a target or prerequisite you must write two of them, '$$'. If you have enabled secondary expansion and you want a literal dollar sign in the prerequisites list, you must actually write four dollar signs ('$$$$').

Recipes and Executing Shells

make starts new sub shell for each line of the recipe.

Setting Environment Variables for Recipe Commands

Write all the environment variables you want to set in the environment of the recipe command in a file, possibly with another target:

Source the file on the same line as the command you want to provide environment variables to (this is because make starts a sub-shell for each recipe line.

pre-experiment:
	echo "COLOR=FUCHSIA" > $(CURDIR)/build/.env
experiment: pre-experiment
	. $(CURDIR)/build/.env; report-color

To specify an environment variable verbatim in a recipe, you will need to use $$ to prevent make from doing its own variable substitution. Also, because different lines are executed by different shells, the definition of the variable and the use of the variable must be on the same line.

some-target:
  COLOR="red"; echo "$${COLOR}"

.PHONY

https://www.gnu.org/software/make/manual/make.html#Phony-Targets

By default, make targets are assumed to be files on disk. They will be built from other files as result of executing make with that name as argument. However, sometimes you want make to run commands that do not represent physical files in the filesystem, and if there's a file with the same name in the filesystem, make will be confused and will pick up the file. To avoid this, you can disambiguate with .PHONY:

.PHONY: clean
clean: 
  rm -rf *.o

.DEFAULT_GOAL

https://www.gnu.org/software/make/manual/html_node/Special-Variables.html#index-_002eDEFAULT_005fGOAL-_0028define-default-goal_0029
.DEFAULT_GOAL := some_target

Variables

CURDIR

CURDIR refers to the directory make is run from:

something:
	"$(CURDIR)/scripts/something.sh"

Automatic Variables

https://www.gnu.org/software/make/manual/make.html#Automatic-Variables

$@

The file name of the target of the rule. In a pattern rule that has multiple targets $@ is the name of whichever target caused the rule’s recipe to be run.

$<

The name of the first prerequisite. For this rule:

types.gen.go: petstore.yaml
	oapi-codegen -generate types -package petstore $< > $@

$< contains "petstore.yaml"

Custom Variables

https://www.gnu.org/software/make/manual/make.html#Using-Variables

Variables allow a text string to be defined once and substituted in multiple places later. A variable is a name defined in Makefile to represent a string of text, called the variable's value. These value are substituted in targets, prerequisites and other parts of the make file. A variable name may be any sequence of characters not containing ":", "#", "=", or whitespace. Variable names beginning with "." and an uppercase letter may be given special meaning in future versions of make. Variable names are case sensitive. It is traditional to use upper case letters in variable names, but we recommend using lower case letters for variable names that serve internal purposes in the makefile, and reserving upper case for parameters that control implicit rules or for parameters that the user should override with command options.

This is how a variable is declared:

my_var = something

This is how a variable is used:

prog.o: $(my_var)

Variables can be used in the value of other variables:

my_var = something
my_other_var = ./$(my_var)/other

Initializing a Custom Variable with the Result of a Command Execution

Use the shell function:

some_var = $(shell $(CURDIR)/scripts/some-script.sh)

Functions

shell Function

https://www.gnu.org/software/make/manual/make.html#Shell-Function

The shell function does command expansion: it takes as an argument a shell command and executes the command, expanding it to the output of the the command:

test: build
	env	MY_PRIVATE_KEY=$(shell ./scripts/get-my-private-key) go test ./...

The shell function removes the trailing new lines and replaces the intermediate new lines with spaces.

!= Shell Assignment Operator

https://www.gnu.org/software/make/manual/make.html#Setting

The != shell assignment operator is similar to the shell function. It removes the trailing new lines and replaces the intermediate new lines with spaces.