1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
# shmk
shmk is a simple utility to build complicated shell projects
## Usage
### single file
shmk can be invoked on a single sh file to "build" it:
```sh
$ shmk myprog.sh file_output.sh
```
### in a wider project
shmk can also serve as a "make" tool, building libraries and executables, running tests (checks) and installing your project to a path.
see [shmk project](#shmk project) for more info
## Directives
Shmk will take each file and parse it before making an output. Most of the file will remain unchanged, however some directives will be parsed:
### `#include file`
Will include a file 'in place'. Will not include a file more than once within the output
The first file with the given name will be used. The search path by default follows this order:
```
./
$DIST/
/usr/lib/
/usr/local/lib/
/usr/share/shmk/
```
Using the `-I` option will prepend a file to this list. If no `.sh` extension is given, both the `filenanme` and the `filename.sh` will be checked
# shmk project
A shmk project is typically built using a `build.shmk` file
An example build shmk file could like this (chek this project's shmk file for more examples):
```sh
#!/usr/bin/env shmk
LIBS="
src/lib/mylibrary.sh
src/lib/second_library.sh
"
PROGS="
src/myutil.sh
"
CHECKS="
tests/test_myutil.sh
"
```
By making this file executable, shmk will be invoked via its shebang and it will parse this file as a project fille.
The difference between a lib and a prog (library and program) is functionally only in where the files get installed. Programs should be intsalled to a `bin/` directory and are inteded to be run directly. Libraries, even though they are functionally shell programs, are intended to be included by other shell programs and provide variables and functions that are to be used.
## stages
When shmk builds a project, it is able to execute the following steps: (by default in the given order)
- **clean**
- cleans the project files
- removes outputted files, executables etc
- **build**
- builds all libraries and programs using shmk
- **check**
- run all the available tests
- **install**
- install binaries and libraries
- by default will install progs to `/usr/local/bin/` and libraries to `/usr/local/lib/`
- `/usr/local/` can be changed using the env var `$PREFIX`
- instead of installing to system, package maintainers may use `$DESTDIR` to choose where to install shmk
- **uninstall**
- this stage is not run by default
- opposite of install, will follow the same install path and remove any libraries or programs it would have installed
## custom build stages
If desired, a custom build stage can be created:
```sh
prog_mycprog () {
gcc -o ${DIST}/myprog src/myprog.c
}
```
Any function prefixed with `prog_` or `lib_` will be treated as an extra program or library to be built, and said function will be run after handling all of the files mentioned in `LIBS` and `PROGS` variables. This will not override anything from these lists.
These
As per the example, this can be useful for incorporating non-shmk build stages. As shmk is interpreted like a normal shell file, the syntax should be the same as a shell allowing for extensible configuration of build stages.
The prefix `check_` can also be used for custom check stages. These will not override the exsiting checks
### Checks and tests
A test in shmk is called a `check` (since test is already a shell command). The testing framework is rather rudimentary, and currenty can only be used with custom `check_` prefixed fucntions in the shmk build. Alternatively binaries from the `$CHECKS` variable will also be run. These are not to be confused with other build stages where the programs are never executed themselves: checks are run as-is.
Checks are run consecutively until either all checks reutrn 0 (success) or a single check returns 1.
This feature is intended to be used with the `shtests` tool.
## Syntax and formatting
### shell features
shmk is intended to be as portable as possible, following exclusively POSIX shell syntax. This means that unlike in bash or csh, there is no formal structure for lists, instead whitespace separated strings are used. New lines or spaces both work, however for the sake of simplicity, newlines are prefered.
### env vars
shmk exposes a few different environment variables in the build environment (ie to be used in custom build stages):
- `${DIST}` - temporary "out" directory where libraries and binaries are placed.
- `${PREFIX}` - where things will be installed
|
