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.

[Project Page] [Download] [Discussion Forum]

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 1 6.

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

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_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

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.

John Graham-Cumming's work on this project was sponsored by Electric Cloud, Inc.