GNU Make Standard Library
The GNU Make Standard Library (GMSL) is a collection of functions
implemented using native GNU Make functionality that provide list and
string manipulation, integer arithmetic, associative arrays, stacks,
and debugging facilities. The GMSL is released under the BSD License.
Using GMSL
The two files needed are gmsl
and __gmsl. To
include the GMSL in your Makefile do
include gmsl
gmsl automatically includes __gmsl. To check that
you have the right version of gmsl
use the gmsl_compatible
function (see
below). The current version is 1 2 3.
The GMSL package also includes a test suite for GMSL. Just run make -f gmsl-tests.
Logical Operators
GMSL has boolean $(true) (a non-empty string)
and $(false) (an empty string). The following operators can be
used with those variables.
not
Arguments: A boolean value
Returns: Returns $(true) if the boolean is $(false) and vice versa
and
Arguments: Two boolean values
Returns: Returns $(true) if both of the booleans are true
or
Arguments: Two boolean values
Returns: Returns $(true) if either of the booleans is true
xor
Arguments: Two boolean values
Returns: Returns $(true) if exactly one of the booleans is true
nand
Arguments: Two boolean values
Returns: Returns value of ‘not and’
nor
Arguments: Two boolean values
Returns: Returns value of ‘not or’
xnor
Arguments: Two boolean values
Returns: Returns value of ‘not xor’
List Manipulation Functions
A list is a string of characters; the list separator is a space.
first
Arguments: 1: A list
Returns: Returns the first element of a list
last
Arguments: 1: A list
Returns: Returns the last element of a list
rest
Arguments: 1: A list
Returns: Returns the list with the first element
removed
chop
Arguments: 1: A list
Returns: Returns the list with the last element removed
map
Arguments: 1: Name of function to
$(call) for each element of list
2: List to
iterate over calling the function in 1
Returns: The list after calling the function on each
element
pairmap
Arguments: 1: Name of function to
$(call) for each pair of elements
2: List to
iterate over calling the function in 1
3: Second
list to iterate over calling the function in 1
Returns: The list after calling the function on each
pair of elements
fold
Arguments: 1: Name of function to $(call) for each element of list
This function takes two arguments
2: List to
iterate over calling the function in 1
Returns: The result of calling the function in 1 on each element in
the list with the previous result of calling 1 as the second
argument.
leq
Arguments: 1: A list to compare
against…
2: …this
list
Returns: Returns $(true) if the two lists are identical
lne
Arguments: 1: A list to compare
against…
2: …this
list
Returns: Returns $(true) if the two lists are different
reverse
Arguments: 1: A list to reverse
Returns: The list with its elements in reverse order
uniq
Arguments: 1: A list to deduplicate
Returns: The list with elements in order without duplicates
length
Arguments: 1: A list
Returns: The number of elements in the list
String Manipulation Functions
A string is any sequence of characters.
seq
Arguments: 1: A string to compare
against…
2: …this
string
Returns: Returns $(true) if the two strings are
identical
sne
Arguments: 1: A string to compare
against…
2: …this
string
Returns: Returns $(true) if the two strings are not
the same
strlen
Arguments: 1: A string
Returns: Returns the length of the string
substr
Arguments: 1: A string
2: Start offset (first character is 1)
3: Ending offset (inclusive)
Returns: Returns a substring
split
Arguments: 1: The character to
split on
2: A
string to split
Returns: Splits a string into a list separated by
spaces at the split
character
in the first argument
merge
Arguments: 1: The character to
put between fields
2: A list
to merge into a string
Returns: Merges a list into a single string, list
elements are separated
by the
character in the first argument
tr
Arguments: 1: The list of
characters to translate from
2: The
list of characters to translate to
3: The
text to translate
Returns: Returns the text after translating characters
uc
Arguments: 1: Text to upper case
Returns: Returns the text in upper case
lc
Arguments: 1: Text to lower case
Returns: Returns the text in lower case
Set Manipulation Functions
Sets are represented by sorted, deduplicated lists. To create a set
from a list use set_create, or start with the empty_set and set_insert individual elements.
The empty set is defined as empty_set.
set_create
Arguments: 1: A list of set elements
Returns: Returns the newly created set
set_insert
Arguments: 1: A single element to add to a set
2: A set
Returns: Returns the set with the element added
set_remove
Arguments: 1: A single element to remove from a set
2: A set
Returns: Returns the set with the element removed
set_is_member
Arguments: 1: A single element
2: A set
Returns: Returns $(true) if the element is in the set
set_is_not_member
Arguments: 1: A single element
2: A set
Returns: Returns $(false) if the element is in the set
set_union
Arguments: 1: A set
2: Another set
Returns: Returns the union of the two sets
set_intersection
Arguments: 1: A set
2: Another set
Returns: Returns the intersection of the two sets
set_is_subset
Arguments: 1: A set
2: Another set
Returns: Returns $(true) if the first set is a subset of the second
set_equal
Arguments: 1: A set
2: Another set
Returns: Returns $(true) if the two sets are identical
Integer Arithmetic Functions
Integers are represented by lists with the equivalent number of
x’s. For example the number 4 is x x x x. The maximum
integer that the library can handle as input (i.e. as the argument to a
call to int_encode) is
65536. There is no limit on integer size for internal computations or
output.
The arithmetic library functions come in two forms: one form of each
function takes integers as arguments and the other form takes the
encoded form (x’s created by a call to int_encode). For example,
there are two plus functions: plus
(called with integer arguments and returns an integer) and int_plus (called with encoded
arguments and returns an encoded result).
plus will be slower than int_plus because its arguments
and result have to be translated between the x’s format and
integers. If doing a complex calculation use the int_* forms with a single
encoding of inputs and single decoding of the output. For simple
calculations the direct forms can be used.
int_decode
Arguments: 1: A number of x’s
representation
Returns: Returns the integer for human consumption
that is represented
by the
string of x’s
int_encode
Arguments: 1: A number in
human-readable integer form
Returns: Returns the integer encoded as a string of x’s
int_plus
Arguments: 1: A number in x’s
representation
2: Another
number in x’s represntation
Returns: Returns the sum of the two numbers in x’s
representation
plus (wrapped version of int_plus)
Arguments: 1: An integer
2: Another
integer
Returns: Returns the sum of the two integers
int_subtract
Arguments: 1: A number in x’s
representation
2: Another
number in x’s represntation
Returns: Returns the difference of the two numbers in
x’s representation,
or outputs
an error on a numeric underflow
subtract (wrapped version of int_subtract)
Arguments: 1: An integer
2: Another
integer
Returns: Returns the difference of the two integers,
or outputs
an error on a numeric underflow
int_multiply
Arguments: 1: A number in x’s
representation
2: Another
number in x’s represntation
Returns: Returns the product of the two numbers in x’s
representation
multiply (wrapped version of int_multiply)
Arguments: 1: An integer
2: Another
integer
Returns: Returns the product of the two integers
int_divide
Arguments: 1: A number in x’s
representation
2: Another
number in x’s represntation
Returns: Returns the result of integer division of
argument 1 divided
by
argument 2 in x’s representation
divide (wrapped version of int_divide)
Arguments: 1: An integer
2: Another
integer
Returns: Returns the integer division of the first
argument by the second
int_modulo
Arguments: 1: A number in x’s
representation
2: Another
number in x’s represntation
Returns: Returns the remainder of integer division of
argument 1 divided
by
argument 2 in x’s representation
modulo (wrapped version of int_modulo)
Arguments: 1: An integer
2: Another
integer
Returns: Returns the remainder of integer division of the first
argument by the second
int_max, int_min
Arguments: 1: A number in x’s
representation
2: Another
number in x’s represntation
Returns: Returns the maximum or minimum of its
arguments in x’s
representation
max, min
Arguments: 1: An integer
2: Another
integer
Returns: Returns the maximum or minimum of its integer
arguments
int_gt, int_gte, int_lt, int_lte, int_eq, int_ne
Arguments: Two x’s representation
numbers to be compared
Returns: $(true) or $(false)
int_gt First argument greater than second argument
int_gte First argument greater than or equal to second argument
int_lt First argument less than second argument
int_lte First argument less than or equal to second argument
int_eq First argument is numerically equal to the second argument
int_ne First argument is not numerically equal to the second argument
gt, gte, lt, lte, eq, ne
Arguments: Two integers to be
compared
Returns: $(true) or $(false)
gt First argument greater than second argument
gte First argument greater than or equal to second argument
lt First argument less than second argument
lte First argument less than or equal to second argument
eq First argument is numerically equal to the second argument
ne First argument is not numerically equal to the second argument
increment adds 1 to its argument, decrement subtracts 1. Note that
decrement does not range check and hence will not underflow, but
will incorrectly say that 0 – 1 = 0
int_inc
Arguments: 1: A number in x’s
representation
Returns: The number incremented by 1 in x’s
representation
inc
Arguments: 1: An integer
Returns: The argument incremented by 1
int_dec
Arguments: 1: A number in x’s
representation
Returns: The number decremented by 1 in x’s
representation
dec
Arguments: 1: An integer
Returns: The argument decremented by 1
int_double
Arguments: 1: A number in x’s
representation
Returns: The number doubled (i.e. * 2) and returned in
x’s representation
double
Arguments: 1: An integer
Returns: The integer times 2
int_halve
Arguments: 1: A number in x’s
representation
Returns: The number halved (i.e. / 2) and returned in
x’s representation
halve
Arguments: 1: An integer
Returns: The integer divided by 2
sequence
Arguments: 1: An integer
2: An integer
Returns: The sequence [arg1 arg2] if arg1 >= arg2 or [arg2 arg1] if arg2 > arg1
dec2hex, dec2bin, dec2oct
Arguments: 1: An integer
Returns: The decimal argument converted to hexadecimal, binary or octal
Associative Arrays
An associate array maps a key value (a string with no spaces in it) to
a single value (any string).
set
Arguments: 1: Name of associative
array
2: The key
value to associate
3: The
value associated with the key
Returns: Nothing
get
Arguments: 1: Name of associative
array
2: The key
to retrieve
Returns: The value stored in the array for that key
keys
Arguments: 1: Name of associative
array
Returns: Returns a list of all defined keys in the
array
defined
Arguments: 1: Name of associative
array
2: The key
to test
Returns: Returns true if the key is defined (i.e. not
empty)
Named Stacks
A stack is an ordered list of strings (with no spaces in them).
push
Arguments: 1: Name of stack
2: Value
to push onto the top of the stack (must not contain
a space)
Returns: None
pop
Arguments: 1: Name of stack
Returns: Top element from the stack after removing it
peek
Arguments: 1: Name of stack
Returns: Top element from the stack without removing it
depth
Arguments: 1: Name of stack
Returns: Number of items on the stack
Function memoization
To reduce the number of calls to slow functions (such as $(shell) a single memoization function is provided.
memoize
Arguments: 1: Name of function to memoize
2: String argument for the function
Returns: Result of $1 applied to $2 but only calls $1 once for each unique $2
Miscellaneous and Debugging Facilities
GMSL defines the following constants; all are accessed as normal GNU
Make variables by wrapping them in $() or ${}.
| Constant | Value | Purpose |
| true | T | Boolean for $(if) and return from GMSL functions |
| false | Boolean for $(if) and return from GMSL functions |
|
| gmsl_version | 1 0 0 | GMSL version number as list: major minor revision |
gmsl_compatible
Arguments: List containing the desired library version number (maj min
rev)
Returns:
$(true) if this version of the library is compatible
with the requested version number, otherwise $(false)
gmsl-print-% (target not a function)
Arguments: The % should be
replaced by the name of a variable that you
wish to
print out.
Action: Echos the name of the variable that matches
the % and its value.
For
example, ‘make gmsl-print-SHELL’ will output the value of
the SHELL
variable
gmsl-echo-% (target not a function)
Arguments: The % should be
replaced by the name of a variable that you
wish to
print out.
Action: Echos the value of the variable that matches
the %.
For
example, ‘make gmsl-echo-SHELL’ will output the value of
the SHELL
variable
assert
Arguments: 1: A boolean that must
be true or the assertion will fail
2: The
message to print with the assertion
Returns: None
assert_exists
Arguments: 1: Name of file that
must exist, if it is missing an assertion
will be
generated
Returns: None
GMSL has a number of environment variables (or command-line overrides)
that control various bits of functionality:
| Variable | Purpose |
| GMSL_NO_WARNINGS | If set prevents GMSL from outputting warning messages: artithmetic functions generate underflow warnings. |
| GMSL_NO_ERRORS | If set prevents GMSL from generating fatal errors: division by zero or failed assertions are fatal. |
| GMSL_TRACE | Enables function tracing. Calls to GMSL functions will result in name and arguments being traced. |
Copyright (c) 2005-2025 John Graham-Cumming.