daylin
/
task.mk
mirror of https://github.com/daylinmorgan/task.mk.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: switch to vhs and add phonify example

This commit is contained in:
Daylin Morgan 2023-01-27 12:39:09 -06:00
parent a901dc63c5
commit 981b29d57a
46 changed files with 331 additions and 3102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -2,4 +2,5 @@
.task.mk
.venv
!docs/examples/**/.task.mk

30
README.md
View File

@ -7,9 +7,7 @@
<p align="center">
<a href="https://gh.dayl.in/task.mk">Documentation</a>
</p>
</div>
</br>
GNU make is an excellent build tool and the task runner we love to hate, but can't escape.
@ -19,20 +17,22 @@ So let's improve the UX to make it the best task runner it can be.
to add some QOL improvements for your users and fellow maintainers.
Current Features:
- ANSI escape code support (including NO_COLOR)
- ANSI escape code support (including NO_COLOR)
- formatted help output
- custom print function
- confirmation prompt
- goal phonifier (disabled by default)
Depends on `GNU Make`, obviously and `Python >=3.7`, and `bash` (or `zsh`).
Wait python?!?!, I'm not `pip` installing some package just to parse my makefile.
I agree, all you need is one file [`.task.mk`](./task.mk).
You can automagically include it with just two additional lines to your `Makefile` (and probably one to your `.gitignore`) and your good to go.
You can automagically include it with just two additional lines to your `Makefile` (and probably one to your `.gitignore`) and you're good to go.
## Setup
One line setup:
One line setup to download .task.mk and add appropriate includes to your `Makefile`.
```bash
bash <(curl -fsSL gh.dayl.in/task.mk/init) # or w/ TASKMK_VERSION=
```
@ -45,7 +45,7 @@ If someone tries to invoke `make help` it will download `.task.mk` for them.
$(if $(filter help,$(MAKECMDGOALS)),$(if $(wildcard .task.mk),,.task.mk: ; curl -fsSL https://raw.githubusercontent.com/daylinmorgan/task.mk/v23.1.1/task.mk -o .task.mk))
```
You might also consider making it a consistently downloaded dependency if you plan to use any of it's advanced feature set, by dropping the `$(MAKECMDGOALS)` check.
If you plan to use any features besides the help prompt you may want to instead commit `.task.mk` to version control or drop the `$(MAKECMDGOALS)` check so it's always downloaded once `make` is invoked.
```make
-include .task.mk
@ -53,21 +53,3 @@ $(if $(wildcard .task.mk),,.task.mk: ; curl -fsSL https://raw.githubusercontent.
```
For more info see the [documentation](https://gh.dayl.in/task.mk).
## Simpler Alternative
But I just want a basic help output, surely I don't need python for this... you would be right.
`Task.mk` replaces my old `make help` recipe boilerplate which may better serve you (so long as you have `sed`/`awk`).
```make
## h, help | show this help
### additional text printed with the help
.PHONY: help h
help h: Makefile
@awk -v fill=$(shell sed -n 's/^## \(.*\) | .*/\1/p' $< | wc -L)\
'match($$0,/^## (.*) \|/,name) && match($$0,/\| (.*)$$/,help)\
{printf "\033[1;93m%*s\033[0m | \033[30m%s\033[0m\n",\
fill,name[1],help[1];} match($$0,/^### (.*)/,str) \
{printf "%*s \033[30m%s\033[0m\n",fill," ",str[1];}' $<
```

167
docs/assets/help.svg
View File

@ -1,4 +1,4 @@
<svg class="rich-terminal shadow" viewBox="0 0 720.3333333333334 716.7333333333333" xmlns="http://www.w3.org/2000/svg">
<svg class="rich-terminal shadow" viewBox="0 0 573.3333333333334 521.5333333333333" xmlns="http://www.w3.org/2000/svg">
<!-- Generated with Rich https://www.textualize.io -->
<style>
@font-face {
@ -16,14 +16,14 @@
font-weight: 700;
}
.terminal-1053897658-matrix {
.terminal-3478059149-matrix {
font-family: Fira Code, monospace;
font-size: 20px;
line-height: 24.4px;
font-variant-east-asian: full-width;
}
.terminal-1053897658-title {
.terminal-3478059149-title {
font-size: 18px;
font-weight: bold;
font-family: arial;
@ -33,133 +33,100 @@
-webkit-filter: drop-shadow( 2px 5px 2px rgba(0, 0, 0, .7));
filter: drop-shadow( 2px 5px 2px rgba(0, 0, 0, .7));
}
.terminal-1053897658-r1 { fill: #94e2d5;font-weight: bold }
.terminal-1053897658-r2 { fill: #c6d0f5 }
.terminal-1053897658-r3 { fill: #f5c2e7;font-weight: bold }
.terminal-1053897658-r4 { fill: #c6d0f5;font-style: italic;;text-decoration: underline; }
.terminal-1053897658-r5 { fill: #a6e3a1;font-weight: bold }
.terminal-1053897658-r6 { fill: #f9e2af;font-weight: bold }
.terminal-1053897658-r7 { fill: #8288a5 }
.terminal-1053897658-r8 { fill: #f38ba8;font-weight: bold }
.terminal-3478059149-r1 { fill: #94e2d5;font-weight: bold }
.terminal-3478059149-r2 { fill: #c6d0f5 }
.terminal-3478059149-r3 { fill: #f5c2e7;font-weight: bold }
.terminal-3478059149-r4 { fill: #c6d0f5;font-style: italic;;text-decoration: underline; }
.terminal-3478059149-r5 { fill: #a6e3a1;font-weight: bold }
.terminal-3478059149-r6 { fill: #f9e2af;font-weight: bold }
.terminal-3478059149-r7 { fill: #8288a5 }
</style>
<defs>
<clipPath id="terminal-1053897658-clip-terminal">
<rect x="0" y="0" width="682.1999999999999" height="633.4" />
<clipPath id="terminal-3478059149-clip-terminal">
<rect x="0" y="0" width="535.8" height="438.2" />
</clipPath>
<clipPath id="terminal-1053897658-line-0">
<rect x="0" y="1.5" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-0">
<rect x="0" y="1.5" width="536.8" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-1">
<rect x="0" y="25.9" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-1">
<rect x="0" y="25.9" width="536.8" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-2">
<rect x="0" y="50.3" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-2">
<rect x="0" y="50.3" width="536.8" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-3">
<rect x="0" y="74.7" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-3">
<rect x="0" y="74.7" width="536.8" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-4">
<rect x="0" y="99.1" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-4">
<rect x="0" y="99.1" width="536.8" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-5">
<rect x="0" y="123.5" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-5">
<rect x="0" y="123.5" width="536.8" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-6">
<rect x="0" y="147.9" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-6">
<rect x="0" y="147.9" width="536.8" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-7">
<rect x="0" y="172.3" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-7">
<rect x="0" y="172.3" width="536.8" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-8">
<rect x="0" y="196.7" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-8">
<rect x="0" y="196.7" width="536.8" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-9">
<rect x="0" y="221.1" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-9">
<rect x="0" y="221.1" width="536.8" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-10">
<rect x="0" y="245.5" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-10">
<rect x="0" y="245.5" width="536.8" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-11">
<rect x="0" y="269.9" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-11">
<rect x="0" y="269.9" width="536.8" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-12">
<rect x="0" y="294.3" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-12">
<rect x="0" y="294.3" width="536.8" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-13">
<rect x="0" y="318.7" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-13">
<rect x="0" y="318.7" width="536.8" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-14">
<rect x="0" y="343.1" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-14">
<rect x="0" y="343.1" width="536.8" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-15">
<rect x="0" y="367.5" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-15">
<rect x="0" y="367.5" width="536.8" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-16">
<rect x="0" y="391.9" width="683.2" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-17">
<rect x="0" y="416.3" width="683.2" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-18">
<rect x="0" y="440.7" width="683.2" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-19">
<rect x="0" y="465.1" width="683.2" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-20">
<rect x="0" y="489.5" width="683.2" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-21">
<rect x="0" y="513.9" width="683.2" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-22">
<rect x="0" y="538.3" width="683.2" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-23">
<rect x="0" y="562.7" width="683.2" height="24.65"/>
</clipPath>
<clipPath id="terminal-1053897658-line-24">
<rect x="0" y="587.1" width="683.2" height="24.65"/>
<clipPath id="terminal-3478059149-line-16">
<rect x="0" y="391.9" width="536.8" height="24.65"/>
</clipPath>
</defs>
<rect fill="#1e1e2e" stroke="rgba(255,255,255,0.35)" stroke-width="1" x="10.1667" y="1" width="700" height="682.4" rx="8"/><text class="terminal-1053897658-title" fill="#c6d0f5" text-anchor="middle" x="350" y="27">make&#160;help</text>
<rect fill="#1e1e2e" stroke="rgba(255,255,255,0.35)" stroke-width="1" x="10.1667" y="1" width="553" height="487.2" rx="8"/><text class="terminal-3478059149-title" fill="#c6d0f5" text-anchor="middle" x="276" y="27">make&#160;help</text>
<g transform="translate(32,22)">
<circle cx="0" cy="0" r="7" fill="#ff5f57"/>
<circle cx="22" cy="0" r="7" fill="#febc2e"/>
<circle cx="44" cy="0" r="7" fill="#28c840"/>
</g>
<g transform="translate(18.166666666666664, 41) scale(.95)" clip-path="url(#terminal-1053897658-clip-terminal)">
<g transform="translate(18.166666666666664, 41) scale(.95)" clip-path="url(#terminal-3478059149-clip-terminal)">
<g class="terminal-1053897658-matrix">
<text class="terminal-1053897658-r1" x="0" y="20" textLength="73.2" clip-path="url(#terminal-1053897658-line-0)">usage:</text><text class="terminal-1053897658-r2" x="683.2" y="20" textLength="12.2" clip-path="url(#terminal-1053897658-line-0)">
</text><text class="terminal-1053897658-r2" x="97.6" y="44.4" textLength="158.6" clip-path="url(#terminal-1053897658-line-1)">make&#160;&lt;recipe&gt;</text><text class="terminal-1053897658-r2" x="683.2" y="44.4" textLength="12.2" clip-path="url(#terminal-1053897658-line-1)">
</text><text class="terminal-1053897658-r2" x="683.2" y="68.8" textLength="12.2" clip-path="url(#terminal-1053897658-line-2)">
</text><text class="terminal-1053897658-r2" x="0" y="93.2" textLength="146.4" clip-path="url(#terminal-1053897658-line-3)">&#160;&#160;Turn&#160;your&#160;</text><text class="terminal-1053897658-r3" x="146.4" y="93.2" textLength="122" clip-path="url(#terminal-1053897658-line-3)">`Makefile`</text><text class="terminal-1053897658-r2" x="268.4" y="93.2" textLength="61" clip-path="url(#terminal-1053897658-line-3)">&#160;into</text><text class="terminal-1053897658-r2" x="683.2" y="93.2" textLength="12.2" clip-path="url(#terminal-1053897658-line-3)">
</text><text class="terminal-1053897658-r2" x="0" y="117.6" textLength="73.2" clip-path="url(#terminal-1053897658-line-4)">&#160;&#160;the&#160;</text><text class="terminal-1053897658-r4" x="73.2" y="117.6" textLength="134.2" clip-path="url(#terminal-1053897658-line-4)">task&#160;runner</text><text class="terminal-1053897658-r2" x="207.4" y="117.6" textLength="231.8" clip-path="url(#terminal-1053897658-line-4)">&#160;you&#160;always&#160;needed.</text><text class="terminal-1053897658-r2" x="683.2" y="117.6" textLength="12.2" clip-path="url(#terminal-1053897658-line-4)">
</text><text class="terminal-1053897658-r2" x="0" y="142" textLength="378.2" clip-path="url(#terminal-1053897658-line-5)">&#160;&#160;See&#160;the&#160;example&#160;output&#160;below.</text><text class="terminal-1053897658-r2" x="683.2" y="142" textLength="12.2" clip-path="url(#terminal-1053897658-line-5)">
</text><text class="terminal-1053897658-r2" x="683.2" y="166.4" textLength="12.2" clip-path="url(#terminal-1053897658-line-6)">
</text><text class="terminal-1053897658-r5" x="24.4" y="190.8" textLength="475.8" clip-path="url(#terminal-1053897658-line-7)">&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;task.mk&#160;development&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;</text><text class="terminal-1053897658-r2" x="683.2" y="190.8" textLength="12.2" clip-path="url(#terminal-1053897658-line-7)">
</text><text class="terminal-1053897658-r2" x="0" y="215.2" textLength="536.8" clip-path="url(#terminal-1053897658-line-8)">&#160;&#160;──────────────────────────────────────────</text><text class="terminal-1053897658-r2" x="683.2" y="215.2" textLength="12.2" clip-path="url(#terminal-1053897658-line-8)">
</text><text class="terminal-1053897658-r6" x="0" y="239.6" textLength="134.2" clip-path="url(#terminal-1053897658-line-9)">&#160;&#160;bootstrap</text><text class="terminal-1053897658-r2" x="134.2" y="239.6" textLength="36.6" clip-path="url(#terminal-1053897658-line-9)">&#160;│&#160;</text><text class="terminal-1053897658-r7" x="170.8" y="239.6" textLength="366" clip-path="url(#terminal-1053897658-line-9)">generate&#160;local&#160;dev&#160;environment</text><text class="terminal-1053897658-r2" x="683.2" y="239.6" textLength="12.2" clip-path="url(#terminal-1053897658-line-9)">
</text><text class="terminal-1053897658-r6" x="0" y="264" textLength="134.2" clip-path="url(#terminal-1053897658-line-10)">&#160;&#160;&#160;&#160;l,&#160;lint</text><text class="terminal-1053897658-r2" x="134.2" y="264" textLength="36.6" clip-path="url(#terminal-1053897658-line-10)">&#160;│&#160;</text><text class="terminal-1053897658-r7" x="170.8" y="264" textLength="183" clip-path="url(#terminal-1053897658-line-10)">lint&#160;the&#160;python</text><text class="terminal-1053897658-r2" x="683.2" y="264" textLength="12.2" clip-path="url(#terminal-1053897658-line-10)">
</text><text class="terminal-1053897658-r6" x="0" y="288.4" textLength="134.2" clip-path="url(#terminal-1053897658-line-11)">&#160;&#160;&#160;&#160;&#160;assets</text><text class="terminal-1053897658-r2" x="134.2" y="288.4" textLength="36.6" clip-path="url(#terminal-1053897658-line-11)">&#160;│&#160;</text><text class="terminal-1053897658-r7" x="170.8" y="288.4" textLength="183" clip-path="url(#terminal-1053897658-line-11)">generate&#160;assets</text><text class="terminal-1053897658-r2" x="683.2" y="288.4" textLength="12.2" clip-path="url(#terminal-1053897658-line-11)">
</text><text class="terminal-1053897658-r6" x="0" y="312.8" textLength="134.2" clip-path="url(#terminal-1053897658-line-12)">&#160;&#160;&#160;&#160;release</text><text class="terminal-1053897658-r2" x="134.2" y="312.8" textLength="36.6" clip-path="url(#terminal-1053897658-line-12)">&#160;│&#160;</text><text class="terminal-1053897658-r7" x="170.8" y="312.8" textLength="366" clip-path="url(#terminal-1053897658-line-12)">release&#160;new&#160;version&#160;of&#160;task.mk</text><text class="terminal-1053897658-r2" x="683.2" y="312.8" textLength="12.2" clip-path="url(#terminal-1053897658-line-12)">
</text><text class="terminal-1053897658-r6" x="0" y="337.2" textLength="134.2" clip-path="url(#terminal-1053897658-line-13)">&#160;&#160;&#160;c,&#160;clean</text><text class="terminal-1053897658-r2" x="134.2" y="337.2" textLength="36.6" clip-path="url(#terminal-1053897658-line-13)">&#160;│&#160;</text><text class="terminal-1053897658-r7" x="170.8" y="337.2" textLength="317.2" clip-path="url(#terminal-1053897658-line-13)">remove&#160;the&#160;generated&#160;files</text><text class="terminal-1053897658-r2" x="683.2" y="337.2" textLength="12.2" clip-path="url(#terminal-1053897658-line-13)">
</text><text class="terminal-1053897658-r2" x="0" y="361.6" textLength="536.8" clip-path="url(#terminal-1053897658-line-14)">&#160;&#160;──────────────────────────────────────────</text><text class="terminal-1053897658-r2" x="683.2" y="361.6" textLength="12.2" clip-path="url(#terminal-1053897658-line-14)">
</text><text class="terminal-1053897658-r2" x="683.2" y="386" textLength="12.2" clip-path="url(#terminal-1053897658-line-15)">
</text><text class="terminal-1053897658-r8" x="24.4" y="410.4" textLength="475.8" clip-path="url(#terminal-1053897658-line-16)">&#160;&#160;&#160;&#160;&#160;&#160;examples&#160;of&#160;task.mk&#160;features&#160;&#160;&#160;&#160;&#160;</text><text class="terminal-1053897658-r2" x="683.2" y="410.4" textLength="12.2" clip-path="url(#terminal-1053897658-line-16)">
</text><text class="terminal-1053897658-r2" x="0" y="434.8" textLength="536.8" clip-path="url(#terminal-1053897658-line-17)">&#160;&#160;──────────────────────────────────────────</text><text class="terminal-1053897658-r2" x="683.2" y="434.8" textLength="12.2" clip-path="url(#terminal-1053897658-line-17)">
</text><text class="terminal-1053897658-r6" x="0" y="459.2" textLength="134.2" clip-path="url(#terminal-1053897658-line-18)">&#160;&#160;&#160;&#160;&#160;list-%</text><text class="terminal-1053897658-r2" x="134.2" y="459.2" textLength="36.6" clip-path="url(#terminal-1053897658-line-18)">&#160;│&#160;</text><text class="terminal-1053897658-r7" x="170.8" y="459.2" textLength="366" clip-path="url(#terminal-1053897658-line-18)">use&#160;pathlib.Path&#160;to&#160;list&#160;files</text><text class="terminal-1053897658-r2" x="683.2" y="459.2" textLength="12.2" clip-path="url(#terminal-1053897658-line-18)">
</text><text class="terminal-1053897658-r7" x="170.8" y="483.6" textLength="512.4" clip-path="url(#terminal-1053897658-line-19)">name&#160;the&#160;directory&#160;in&#160;rule&#160;(make&#160;list-src)</text><text class="terminal-1053897658-r2" x="683.2" y="483.6" textLength="12.2" clip-path="url(#terminal-1053897658-line-19)">
</text><text class="terminal-1053897658-r6" x="0" y="508" textLength="134.2" clip-path="url(#terminal-1053897658-line-20)">&#160;&#160;&#160;&#160;&#160;&#160;&#160;info</text><text class="terminal-1053897658-r2" x="134.2" y="508" textLength="36.6" clip-path="url(#terminal-1053897658-line-20)">&#160;│&#160;</text><text class="terminal-1053897658-r7" x="170.8" y="508" textLength="329.4" clip-path="url(#terminal-1053897658-line-20)">demonstrate&#160;usage&#160;of&#160;tprint</text><text class="terminal-1053897658-r2" x="683.2" y="508" textLength="12.2" clip-path="url(#terminal-1053897658-line-20)">
</text><text class="terminal-1053897658-r6" x="0" y="532.4" textLength="134.2" clip-path="url(#terminal-1053897658-line-21)">&#160;&#160;&#160;&#160;&#160;&#160;check</text><text class="terminal-1053897658-r2" x="134.2" y="532.4" textLength="36.6" clip-path="url(#terminal-1053897658-line-21)">&#160;│&#160;</text><text class="terminal-1053897658-r7" x="170.8" y="532.4" textLength="353.8" clip-path="url(#terminal-1053897658-line-21)">get&#160;user&#160;confirmation&#160;or&#160;exit</text><text class="terminal-1053897658-r2" x="683.2" y="532.4" textLength="12.2" clip-path="url(#terminal-1053897658-line-21)">
</text><text class="terminal-1053897658-r2" x="0" y="556.8" textLength="536.8" clip-path="url(#terminal-1053897658-line-22)">&#160;&#160;──────────────────────────────────────────</text><text class="terminal-1053897658-r2" x="683.2" y="556.8" textLength="12.2" clip-path="url(#terminal-1053897658-line-22)">
</text><text class="terminal-1053897658-r6" x="0" y="581.2" textLength="134.2" clip-path="url(#terminal-1053897658-line-23)">&#160;&#160;&#160;&#160;h,&#160;help</text><text class="terminal-1053897658-r2" x="134.2" y="581.2" textLength="36.6" clip-path="url(#terminal-1053897658-line-23)">&#160;│&#160;</text><text class="terminal-1053897658-r7" x="170.8" y="581.2" textLength="170.8" clip-path="url(#terminal-1053897658-line-23)">show&#160;this&#160;help</text><text class="terminal-1053897658-r2" x="683.2" y="581.2" textLength="12.2" clip-path="url(#terminal-1053897658-line-23)">
</text><text class="terminal-1053897658-r2" x="683.2" y="605.6" textLength="12.2" clip-path="url(#terminal-1053897658-line-24)">
</text><text class="terminal-1053897658-r2" x="0" y="630" textLength="561.2" clip-path="url(#terminal-1053897658-line-25)">for&#160;more&#160;info:&#160;github.com/daylinmorgan/task.mk</text><text class="terminal-1053897658-r2" x="683.2" y="630" textLength="12.2" clip-path="url(#terminal-1053897658-line-25)">
<g class="terminal-3478059149-matrix">
<text class="terminal-3478059149-r1" x="0" y="20" textLength="61" clip-path="url(#terminal-3478059149-line-0)">usage</text><text class="terminal-3478059149-r2" x="61" y="20" textLength="12.2" clip-path="url(#terminal-3478059149-line-0)">:</text><text class="terminal-3478059149-r2" x="536.8" y="20" textLength="12.2" clip-path="url(#terminal-3478059149-line-0)">
</text><text class="terminal-3478059149-r2" x="97.6" y="44.4" textLength="158.6" clip-path="url(#terminal-3478059149-line-1)">make&#160;&lt;recipe&gt;</text><text class="terminal-3478059149-r2" x="536.8" y="44.4" textLength="12.2" clip-path="url(#terminal-3478059149-line-1)">
</text><text class="terminal-3478059149-r2" x="536.8" y="68.8" textLength="12.2" clip-path="url(#terminal-3478059149-line-2)">
</text><text class="terminal-3478059149-r2" x="0" y="93.2" textLength="146.4" clip-path="url(#terminal-3478059149-line-3)">&#160;&#160;Turn&#160;your&#160;</text><text class="terminal-3478059149-r3" x="146.4" y="93.2" textLength="122" clip-path="url(#terminal-3478059149-line-3)">`Makefile`</text><text class="terminal-3478059149-r2" x="268.4" y="93.2" textLength="61" clip-path="url(#terminal-3478059149-line-3)">&#160;into</text><text class="terminal-3478059149-r2" x="536.8" y="93.2" textLength="12.2" clip-path="url(#terminal-3478059149-line-3)">
</text><text class="terminal-3478059149-r2" x="0" y="117.6" textLength="73.2" clip-path="url(#terminal-3478059149-line-4)">&#160;&#160;the&#160;</text><text class="terminal-3478059149-r4" x="73.2" y="117.6" textLength="134.2" clip-path="url(#terminal-3478059149-line-4)">task&#160;runner</text><text class="terminal-3478059149-r2" x="207.4" y="117.6" textLength="231.8" clip-path="url(#terminal-3478059149-line-4)">&#160;you&#160;always&#160;needed.</text><text class="terminal-3478059149-r2" x="536.8" y="117.6" textLength="12.2" clip-path="url(#terminal-3478059149-line-4)">
</text><text class="terminal-3478059149-r2" x="0" y="142" textLength="378.2" clip-path="url(#terminal-3478059149-line-5)">&#160;&#160;See&#160;the&#160;example&#160;output&#160;below.</text><text class="terminal-3478059149-r2" x="536.8" y="142" textLength="12.2" clip-path="url(#terminal-3478059149-line-5)">
</text><text class="terminal-3478059149-r2" x="536.8" y="166.4" textLength="12.2" clip-path="url(#terminal-3478059149-line-6)">
</text><text class="terminal-3478059149-r5" x="24.4" y="190.8" textLength="475.8" clip-path="url(#terminal-3478059149-line-7)">&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;task.mk&#160;development&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;</text><text class="terminal-3478059149-r2" x="536.8" y="190.8" textLength="12.2" clip-path="url(#terminal-3478059149-line-7)">
</text><text class="terminal-3478059149-r2" x="0" y="215.2" textLength="536.8" clip-path="url(#terminal-3478059149-line-8)">&#160;&#160;──────────────────────────────────────────</text><text class="terminal-3478059149-r2" x="536.8" y="215.2" textLength="12.2" clip-path="url(#terminal-3478059149-line-8)">
</text><text class="terminal-3478059149-r1" x="0" y="239.6" textLength="134.2" clip-path="url(#terminal-3478059149-line-9)">&#160;&#160;bootstrap</text><text class="terminal-3478059149-r2" x="134.2" y="239.6" textLength="36.6" clip-path="url(#terminal-3478059149-line-9)">&#160;│&#160;</text><text class="terminal-3478059149-r3" x="170.8" y="239.6" textLength="366" clip-path="url(#terminal-3478059149-line-9)">generate&#160;local&#160;dev&#160;environment</text><text class="terminal-3478059149-r2" x="536.8" y="239.6" textLength="12.2" clip-path="url(#terminal-3478059149-line-9)">
</text><text class="terminal-3478059149-r6" x="0" y="264" textLength="134.2" clip-path="url(#terminal-3478059149-line-10)">&#160;&#160;&#160;&#160;&#160;l&#160;lint</text><text class="terminal-3478059149-r2" x="134.2" y="264" textLength="36.6" clip-path="url(#terminal-3478059149-line-10)">&#160;│&#160;</text><text class="terminal-3478059149-r7" x="170.8" y="264" textLength="183" clip-path="url(#terminal-3478059149-line-10)">lint&#160;the&#160;python</text><text class="terminal-3478059149-r2" x="536.8" y="264" textLength="12.2" clip-path="url(#terminal-3478059149-line-10)">
</text><text class="terminal-3478059149-r6" x="0" y="288.4" textLength="134.2" clip-path="url(#terminal-3478059149-line-11)">&#160;&#160;&#160;&#160;&#160;assets</text><text class="terminal-3478059149-r2" x="134.2" y="288.4" textLength="36.6" clip-path="url(#terminal-3478059149-line-11)">&#160;│&#160;</text><text class="terminal-3478059149-r7" x="170.8" y="288.4" textLength="183" clip-path="url(#terminal-3478059149-line-11)">generate&#160;assets</text><text class="terminal-3478059149-r2" x="536.8" y="288.4" textLength="12.2" clip-path="url(#terminal-3478059149-line-11)">
</text><text class="terminal-3478059149-r6" x="0" y="312.8" textLength="134.2" clip-path="url(#terminal-3478059149-line-12)">&#160;&#160;&#160;&#160;release</text><text class="terminal-3478059149-r2" x="134.2" y="312.8" textLength="36.6" clip-path="url(#terminal-3478059149-line-12)">&#160;│&#160;</text><text class="terminal-3478059149-r7" x="170.8" y="312.8" textLength="366" clip-path="url(#terminal-3478059149-line-12)">release&#160;new&#160;version&#160;of&#160;task.mk</text><text class="terminal-3478059149-r2" x="536.8" y="312.8" textLength="12.2" clip-path="url(#terminal-3478059149-line-12)">
</text><text class="terminal-3478059149-r6" x="0" y="337.2" textLength="134.2" clip-path="url(#terminal-3478059149-line-13)">&#160;&#160;&#160;&#160;c&#160;clean</text><text class="terminal-3478059149-r2" x="134.2" y="337.2" textLength="36.6" clip-path="url(#terminal-3478059149-line-13)">&#160;│&#160;</text><text class="terminal-3478059149-r7" x="170.8" y="337.2" textLength="317.2" clip-path="url(#terminal-3478059149-line-13)">remove&#160;the&#160;generated&#160;files</text><text class="terminal-3478059149-r2" x="536.8" y="337.2" textLength="12.2" clip-path="url(#terminal-3478059149-line-13)">
</text><text class="terminal-3478059149-r6" x="0" y="361.6" textLength="134.2" clip-path="url(#terminal-3478059149-line-14)">&#160;&#160;&#160;&#160;&#160;&#160;&#160;info</text><text class="terminal-3478059149-r2" x="134.2" y="361.6" textLength="36.6" clip-path="url(#terminal-3478059149-line-14)">&#160;│&#160;</text><text class="terminal-3478059149-r7" x="170.8" y="361.6" textLength="329.4" clip-path="url(#terminal-3478059149-line-14)">demonstrate&#160;usage&#160;of&#160;tprint</text><text class="terminal-3478059149-r2" x="536.8" y="361.6" textLength="12.2" clip-path="url(#terminal-3478059149-line-14)">
</text><text class="terminal-3478059149-r6" x="0" y="386" textLength="134.2" clip-path="url(#terminal-3478059149-line-15)">&#160;&#160;&#160;&#160;&#160;h&#160;help</text><text class="terminal-3478059149-r2" x="134.2" y="386" textLength="36.6" clip-path="url(#terminal-3478059149-line-15)">&#160;│&#160;</text><text class="terminal-3478059149-r7" x="170.8" y="386" textLength="170.8" clip-path="url(#terminal-3478059149-line-15)">show&#160;this&#160;help</text><text class="terminal-3478059149-r2" x="536.8" y="386" textLength="12.2" clip-path="url(#terminal-3478059149-line-15)">
</text><text class="terminal-3478059149-r2" x="536.8" y="410.4" textLength="12.2" clip-path="url(#terminal-3478059149-line-16)">
</text><text class="terminal-3478059149-r2" x="0" y="434.8" textLength="402.6" clip-path="url(#terminal-3478059149-line-17)">for&#160;more&#160;info:&#160;gh.dayl.in/task.mk</text><text class="terminal-3478059149-r2" x="536.8" y="434.8" textLength="12.2" clip-path="url(#terminal-3478059149-line-17)">
</text>
</g>
</g>

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 12 KiB

1
docs/examples/.bashrc
View File

@ -1 +0,0 @@
export PS1='task.mk demo % '

19
docs/examples/Makefile
View File

@ -1,18 +1,13 @@
MAKEFLAGS += --no-print-directory
COLS ?= 60
ROWS ?= 20
EXAMPLES := check embedded recipe-help
CASTS := $(addsuffix /demo.cast, $(EXAMPLES))
EXAMPLES := check embedded recipe-help phonify
GIFS := $(addsuffix /demo.gif, $(EXAMPLES))
all: $(CASTS)
all: $(GIFS)
%/demo.cast: %/record.sh
asciinema rec --cols $(COLS) --rows $(ROWS) --overwrite -c $< $@
check/demo.cast: COLS = 48
check/demo.cast: ROWS = 12
%/demo.gif: %/demo.tape %/Makefile
cd $* && vhs < demo.tape
clean:
rm -rf $(CASTS)
rm -rf $(GIFS)
.PHONY:all clean
.PHONY: all clean

1
docs/examples/check/.task.mk Symbolic link
View File

@ -0,0 +1 @@
../../../task.mk

11
docs/examples/check/Makefile Normal file
View File

@ -0,0 +1,11 @@
.PHONY: check
check: ## get user confirmation or exit
$(call tconfirm,Would you like to proceed?)
@echo "you said yes!"
define USAGE
{a.$(HEADER_STYLE)}usage:{a.end}\n make <recipe>\n\n interactivity w/ task.mk\n
endef
.DEFAULT_GOAL = help
include .task.mk

16
docs/examples/check/check.mk
View File

@ -1,16 +0,0 @@
## check | get user confirmation or exit
.PHONY: check
check:
$(call tconfirm,Would you like to proceed?)
@echo "you said yes!"
define USAGE
{a.$(HEADER_STYLE)}usage:{a.end}
make <recipe>
interactivity w/ task.mk\n
endef
.DEFAULT_GOAL = help
include $(shell git rev-parse --show-toplevel)/task.mk

BIN
docs/examples/check/demo.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 335 KiB

15
docs/examples/check/demo.tape Normal file
View File

@ -0,0 +1,15 @@
Output demo.gif
Set FontSize 32
Set Width 1600
Set Height 800
Set Theme "Catppuccin Mocha"
Type "make help" Sleep 1s Enter Sleep 2s
Type "make check" Sleep 1s Enter Sleep 2s
Type "y" Sleep 1s Enter Sleep 2s
Type "# Let's try again but instead say no this time" Sleep 1s Enter
Type "make check" Sleep 1s Enter Sleep 2s
Type "n" Sleep 1s Enter Sleep 2s
Sleep 2s

10
docs/examples/check/index.md
View File

@ -1,12 +1,8 @@
---
asciinema: true
---
# Check
<div id="demo-cast"></div>
![demo](./demo.gif)
```make title="check.mk"
--8<-- "docs/examples/check/check.mk"
```make title="Makefile (check)"
--8<-- "docs/examples/check/Makefile"
```

10
docs/examples/check/record.sh
View File

@ -1,10 +0,0 @@
#!/usr/bin/env bash
source "$(dirname "${BASH_SOURCE[0]}")/../functions.sh"
cmd 'make -f check/check.mk help'
cmd 'make -f check/check.mk check'
msg "# Let's try again but instead say no this time"
cmd 'make -f check/check.mk check'
sleep 1

1
docs/examples/embedded/.task.mk Symbolic link
View File

@ -0,0 +1 @@
../../../task.mk

35
docs/examples/embedded/Makefile Normal file
View File

@ -0,0 +1,35 @@
### examples of task.mk features |> --divider --align center --msg-style b_red
define list_files_py
from pathlib import Path
print("files in $(2)")
print([f.name for f in (Path("$(2)").iterdir())])
endef
## list-% |> use pathlib.Path to list files
### name the directory in rule (make list-src) |> --align sep
list-%:
$(call py,list_files_py,$*)
# dollar signs will always be a problem :|
define bash_script
echo "Is the process running bash? We can check with ps"
ps -o args= -p $$$$ | grep -E -m 1 -o '\w{0,5}sh'
echo "Get input at runtime"
printf "type input now! "
read -r name
echo "you typed -> $$name"
echo "the argument below as given in the makefile itself"
echo "it's expanded before the script is passed to bash"
printf "%s\n" "$(2)"
endef
.PHONY: embedded-bash
embedded-bash: ## bash script with pipes and make input
$(call tbash,bash_script,bash multiline is working 🤞)
define USAGE
{a.$(HEADER_STYLE)}usage:{a.end}\n make <recipe>\n\n examples of embedded scripts in `{a.magenta}Makefile{a.end}`\n
endef
.DEFAULT_GOAL = help
include .task.mk

83
docs/examples/embedded/demo.cast
View File

@ -1,83 +0,0 @@
{"version": 2, "width": 60, "height": 20, "timestamp": 1664060088, "env": {"SHELL": "/usr/bin/zsh", "TERM": "xterm-256color"}}
[0.008131, "o", "\u001b[H\u001b[2J\u001b[3J"]
[0.008522, "o", "bash >> "]
[0.008683, "o", "ma"]
[0.189166, "o", "ke"]
[0.279481, "o", " -"]
[0.369776, "o", "f "]
[0.460021, "o", "em"]
[0.550229, "o", "be"]
[0.640359, "o", "dd"]
[0.730591, "o", "ed"]
[0.820572, "o", "/e"]
[0.910745, "o", "mb"]
[1.091087, "o", "ed"]
[1.181312, "o", "de"]
[1.271441, "o", "d."]
[1.361501, "o", "mk"]
[1.451615, "o", " h"]
[1.541783, "o", "el"]
[1.63204, "o", "p\r\n"]
[2.664242, "o", "\u001b[1;36musage:\u001b[0m\r\n\tmake <recipe>\r\n\t\r\n\texamples of embedded scripts in `\u001b[35mMakefile\u001b[0m`\r\n\r\n \u001b[1;31m examples of task.mk features \u001b[0m\r\n\u001b[38m ─────────────────────────────────────────────────────\u001b[0m\r\n\u001b[1;33m list-%\u001b[0m │ \u001b[2muse pathlib.Path to list files\u001b[0m\r\n \u001b[2mname the directory in rule (make list-src)\u001b[0m\r\n\u001b[1;33m embedded-bash\u001b[0m │ \u001b[2mbash script with pipes and make input\u001b[0m\r\n\u001b[1;33m h, help\u001b[0m │ \u001b[2mshow this help\u001b[0m\r\n\r\n"]
[4.671801, "o", "\u001b[H\u001b[2J\u001b[3Jbash >> "]
[4.67392, "o", "ma"]
[4.854455, "o", "ke"]
[4.944728, "o", " -"]
[5.034921, "o", "f "]
[5.124982, "o", "em"]
[5.215103, "o", "be"]
[5.305188, "o", "dd"]
[5.395353, "o", "ed"]
[5.485457, "o", "/e"]
[5.576246, "o", "mb"]
[5.75589, "o", "ed"]
[5.846014, "o", "de"]
[5.93612, "o", "d."]
[6.026298, "o", "mk"]
[6.11644, "o", " l"]
[6.206464, "o", "is"]
[6.296631, "o", "t-"]
[6.386781, "o", "em"]
[6.477052, "o", "be"]
[6.657201, "o", "dd"]
[6.747412, "o", "ed"]
[6.837566, "o", "\r\n"]
[7.867599, "o", "files in embedded\r\n['embedded.mk', 'demo.cast', 'record.sh', 'index.md']\r\n"]
[9.872436, "o", "\u001b[H\u001b[2J\u001b[3J"]
[9.872754, "o", "bash >> "]
[9.874651, "o", "ma"]
[10.055031, "o", "ke"]
[10.145171, "o", " -"]
[10.235256, "o", "f "]
[10.325347, "o", "em"]
[10.415525, "o", "be"]
[10.505721, "o", "dd"]
[10.595814, "o", "ed"]
[10.685931, "o", "/e"]
[10.776068, "o", "mb"]
[10.956362, "o", "ed"]
[11.046547, "o", "de"]
[11.136692, "o", "d."]
[11.226851, "o", "mk"]
[11.316894, "o", " e"]
[11.406996, "o", "mb"]
[11.497205, "o", "ed"]
[11.58725, "o", "de"]
[11.677471, "o", "d-"]
[11.85761, "o", "ba"]
[11.947917, "o", "sh"]
[12.038071, "o", "\r\n"]
[13.045213, "o", "Is the process running bash? We can check with ps\r\n"]
[13.051057, "o", "bash\r\n"]
[13.051385, "o", "What text to figlet? \r\n"]
[14.434504, "o", "t"]
[14.503239, "o", "a"]
[14.605384, "o", "s"]
[14.745978, "o", "k"]
[14.946139, "o", "."]
[15.080651, "o", "m"]
[15.228545, "o", "k"]
[15.617669, "o", "\r\n"]
[15.618495, "o", " _ _ _ \r\n| |_ __ _ ___| | __ _ __ ___ | | __\r\n| __/ _` / __| |/ / | '_ ` _ \\| |/ /\r\n| || (_| \\__ \\ < _| | | | | | < \r\n \\__\\__,_|___/_|\\_(_)_| |_| |_|_|\\_\\\r\n \r\n"]
[15.618636, "o", "the argument below as given in the makefile itself\r\n"]
[15.618695, "o", "it's expanded before the script is passed to bash\r\nbash multiline is probably working\r\n"]

BIN
docs/examples/embedded/demo.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 701 KiB

13
docs/examples/embedded/demo.tape Normal file
View File

@ -0,0 +1,13 @@
Output demo.gif
Set FontSize 32
Set Width 1600
Set Height 800
Set Theme "Catppuccin Mocha"
Type "make help" Sleep 1s Enter Sleep 2s
Type "make list-'.'" Sleep 1s Enter Sleep 2s
Type "make embedded-bash" Sleep 1s Enter Sleep 2s
Type "input!!" Sleep 500ms Enter Sleep 2s
Sleep 2s

43
docs/examples/embedded/embedded.mk
View File

@ -1,43 +0,0 @@
### examples of task.mk features | args: --divider --align center --msg-style b_red
define list_files_py
from pathlib import Path
print("files in $(2)")
print([f.name for f in (Path("$(2)").iterdir())])
endef
## list-% | use pathlib.Path to list files
### name the directory in rule (make list-src) | args: --align sep
list-%:
$(call py,list_files_py,$*)
# dollar signs will always be a problem
define bash_script
echo "Is the process running bash? We can check with ps"
ps -o args= -p $$$$ | grep -E -m 1 -o '\w{0,5}sh'
if [ -x "$(command -v figlet)" ]; then
echo 'no figlet :('
else
echo "What text to figlet? "
read name
figlet $$name
fi
echo "the argument below as given in the makefile itself"
echo "it's expanded before the script is passed to bash"
printf "%s\n" "$(2)"
endef
## embedded-bash | bash script with pipes and make input
.PHONY: embedded-bash
embedded-bash:
$(call tbash,bash_script,bash multiline is probably working)
define USAGE
{a.$(HEADER_STYLE)}usage:{a.end}
make <recipe>
examples of embedded scripts in `{a.magenta}Makefile{a.end}`
endef
.DEFAULT_GOAL = help
include $(shell git rev-parse --show-toplevel)/task.mk

10
docs/examples/embedded/index.md
View File

@ -1,12 +1,8 @@
---
asciinema: true
---
# Embedded
<div id="demo-cast"></div>
![demo](./demo.gif)
```make title="embedded.mk"
--8<-- "docs/examples/embedded/embedded.mk"
```make title="Makefile (embedded)"
--8<-- "docs/examples/embedded/Makefile"
```

9
docs/examples/embedded/record.sh
View File

@ -1,9 +0,0 @@
#!/usr/bin/env bash
source "$(dirname "${BASH_SOURCE[0]}")/../functions.sh"
cmd 'make -f embedded/embedded.mk help'
cmd 'make -f embedded/embedded.mk list-embedded'
cmd 'make -f embedded/embedded.mk embedded-bash'
sleep 1

15
docs/examples/functions.sh
View File

@ -1,15 +0,0 @@
#!/usr/bin/env bash
msg() {
printf '%s\n' "$1" | pv -qL 20
sleep 1
}
cmd (){
clear
printf 'bash >> '
msg "$1"
$1
sleep 2
}

4
docs/examples/index.md
View File

@ -12,3 +12,7 @@
[Recipe Help](./recipe-help)
: Display the target, docstring and recipe for a given target then exit.
[Phonify](./phonify)
: Automatically generate the phony call for any documented tasks.

1
docs/examples/phonify/.task.mk Symbolic link
View File

@ -0,0 +1 @@
../../../task.mk

22
docs/examples/phonify/Makefile Normal file
View File

@ -0,0 +1,22 @@
a-task: ## will be marked phony
@echo a-task executed
b-task: ## wont be marked phony |> --not-phony
@echo b-task executed
c-task:
@echo c-task executed
.PHONY: gen-task-files
gen-task-files:
touch a-task b-task c-task
define USAGE
{a.$(HEADER_STYLE)}usage:{a.end}\n make <recipe>\n
phonifying tasks
{a.faint}hint: there is also a c-task...{a.end}\n
endef
PHONIFY = true
.DEFAULT_GOAL = help
include .task.mk

0
docs/examples/phonify/a-task Normal file
View File

0
docs/examples/phonify/b-task Normal file
View File

0
docs/examples/phonify/c-task Normal file
View File

BIN
docs/examples/phonify/demo.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 395 KiB

14
docs/examples/phonify/demo.tape Normal file
View File

@ -0,0 +1,14 @@
Output demo.gif
Set FontSize 32
Set Width 1600
Set Height 800
Set Theme "Catppuccin Mocha"
Type "make help" Sleep 1s Enter Sleep 2s
Type "ls" Sleep 1s Enter Sleep 2s
Type "make a-task" Sleep 1s Enter Sleep 2s
Type "make b-task" Sleep 1s Enter Sleep 2s
Type "make c-task" Sleep 1s Enter Sleep 2s
Sleep 2s

8
docs/examples/phonify/index.md Normal file
View File

@ -0,0 +1,8 @@
# Phonify
![demo](./demo.gif)
```make title="Makefile (phonify)"
--8<-- "docs/examples/phonify/Makefile"
```

1
docs/examples/recipe-help/.task.mk Symbolic link
View File

@ -0,0 +1 @@
../../../task.mk

8
docs/examples/recipe-help/recipe-help.mk → docs/examples/recipe-help/Makefile
View File

@ -1,10 +1,8 @@
## deps-only | a task/target with dependencies
.PHONY: deps-only
deps-only: foo
deps-only: foo ## a task/target with dependencies
## foo | a dummy rule that depends on the local files
.PHONY: foo
foo: $(wildcard *)
foo: $(wildcard *) ## a dummy rule that depends on the local files
@echo 'this is a dummy rule'
# bar but no docstring
@ -20,5 +18,5 @@ define USAGE
endef
.DEFAULT_GOAL = help
include $(shell git rev-parse --show-toplevel)/task.mk
include .task.mk

138
docs/examples/recipe-help/demo.cast
View File

@ -1,138 +0,0 @@
{"version": 2, "width": 60, "height": 20, "timestamp": 1664060106, "env": {"SHELL": "/usr/bin/zsh", "TERM": "xterm-256color"}}
[0.007806, "o", "\u001b[H\u001b[2J\u001b[3J"]
[0.008354, "o", "bash >> "]
[0.008532, "o", "ma"]
[0.189207, "o", "ke"]
[0.279458, "o", " -"]
[0.369697, "o", "f "]
[0.459892, "o", "re"]
[0.550111, "o", "ci"]
[0.640099, "o", "pe"]
[0.730309, "o", "-h"]
[0.820408, "o", "el"]
[0.910572, "o", "p/"]
[1.090837, "o", "re"]
[1.180944, "o", "ci"]
[1.271024, "o", "pe"]
[1.36131, "o", "-h"]
[1.451464, "o", "el"]
[1.541712, "o", "p."]
[1.631676, "o", "mk"]
[1.721815, "o", " h"]
[1.812133, "o", "el"]
[1.99248, "o", "p\r\n"]
[3.025715, "o", "\u001b[1;36musage:\u001b[0m\r\n\tmake <recipe>\r\n\tmake help <recipe>\r\n\r\n\u001b[1;33m deps-only\u001b[0m │ \u001b[2ma task/target with dependencies\u001b[0m\r\n\u001b[1;33m foo\u001b[0m │ \u001b[2ma dummy rule that depends on the local files\u001b[0m\r\n\u001b[1;33m h, help\u001b[0m │ \u001b[2mshow this help\u001b[0m\r\n\r\n"]
[5.032814, "o", "\u001b[H\u001b[2J\u001b[3Jbash >> "]
[5.034705, "o", "ma"]
[5.215256, "o", "ke"]
[5.305482, "o", " -"]
[5.395504, "o", "f "]
[5.485805, "o", "re"]
[5.576036, "o", "ci"]
[5.666095, "o", "pe"]
[5.756177, "o", "-h"]
[5.846563, "o", "el"]
[5.93671, "o", "p/"]
[6.11689, "o", "re"]
[6.206935, "o", "ci"]
[6.297128, "o", "pe"]
[6.387205, "o", "-h"]
[6.477454, "o", "el"]
[6.567496, "o", "p."]
[6.657713, "o", "mk"]
[6.747729, "o", " h"]
[6.838006, "o", "el"]
[7.018242, "o", "p "]
[7.108261, "o", "he"]
[7.198405, "o", "lp"]
[7.288809, "o", "\r\n"]
[8.318829, "o", "\u001b[1;36mtask.mk recipe help\u001b[0m\r\n\r\n"]
[8.325694, "o", " \u001b[1;33mh help\u001b[0m\r\n\u001b[38m ────────────────────────────────────────────────────────\u001b[0m\r\n $(call py,help_py) || { echo \"exiting early!\"; exit 1; }\r\n\r\n"]
[8.329695, "o", "exiting early!\r\nmake[1]: *** [/home/daylin/dev/github/mine/task.mk/task.mk:30: help] Error 1\r\n"]
[10.332715, "o", "\u001b[H\u001b[2J\u001b[3J"]
[10.333056, "o", "bash >> "]
[10.335005, "o", "ma"]
[10.515605, "o", "ke"]
[10.605896, "o", " -"]
[10.696226, "o", "f "]
[10.78629, "o", "re"]
[10.876669, "o", "ci"]
[10.966704, "o", "pe"]
[11.056858, "o", "-h"]
[11.146831, "o", "el"]
[11.236969, "o", "p/"]
[11.417281, "o", "re"]
[11.507468, "o", "ci"]
[11.597442, "o", "pe"]
[11.687589, "o", "-h"]
[11.777832, "o", "el"]
[11.867969, "o", "p."]
[11.958105, "o", "mk"]
[12.048177, "o", " h"]
[12.138291, "o", "el"]
[12.318676, "o", "p "]
[12.408796, "o", "de"]
[12.498823, "o", "ps"]
[12.588985, "o", "-o"]
[12.679133, "o", "nl"]
[12.769237, "o", "y\r\n"]
[13.807661, "o", "\u001b[1;36mtask.mk recipe help\u001b[0m\r\n\r\n"]
[13.816448, "o", "\u001b[1;33m deps-only\u001b[0m │ \u001b[2ma task/target with dependencies\u001b[0m\r\n \u001b[38mdeps\u001b[0m: \u001b[2mfoo\u001b[0m\r\n\r\n"]
[13.820255, "o", "exiting early!\r\n"]
[13.820461, "o", "make[1]: *** [/home/daylin/dev/github/mine/task.mk/task.mk:30: help] Error 1\r\n"]
[15.823763, "o", "\u001b[H\u001b[2J\u001b[3J"]
[15.824036, "o", "bash >> "]
[15.826016, "o", "ma"]
[16.006673, "o", "ke"]
[16.09685, "o", " -"]
[16.186936, "o", "f "]
[16.277228, "o", "re"]
[16.367339, "o", "ci"]
[16.45744, "o", "pe"]
[16.547483, "o", "-h"]
[16.637622, "o", "el"]
[16.727742, "o", "p/"]
[16.907989, "o", "re"]
[16.99817, "o", "ci"]
[17.088391, "o", "pe"]
[17.178352, "o", "-h"]
[17.268476, "o", "el"]
[17.358766, "o", "p."]
[17.448842, "o", "mk"]
[17.539039, "o", " h"]
[17.629197, "o", "el"]
[17.809354, "o", "p "]
[17.899578, "o", "fo"]
[17.989694, "o", "o\r\n"]
[19.020047, "o", "\u001b[1;36mtask.mk recipe help\u001b[0m\r\n\r\n"]
[19.03039, "o", "\u001b[1;33m foo\u001b[0m │ \u001b[2ma dummy rule that depends on the local files\u001b[0m\r\n \u001b[38mdeps\u001b[0m: \u001b[2mcheck embedded functions.sh index.md Makefile recipe-help\u001b[0m\r\n\u001b[38m ────────────────────────────\u001b[0m\r\n @echo 'this is a dummy rule'\r\n\r\n"]
[19.035496, "o", "exiting early!\r\n"]
[19.035706, "o", "make[1]: *** [/home/daylin/dev/github/mine/task.mk/task.mk:30: help] Error 1\r\n"]
[21.039168, "o", "\u001b[H\u001b[2J\u001b[3J"]
[21.03927, "o", "bash >> "]
[21.041378, "o", "ma"]
[21.221916, "o", "ke"]
[21.31205, "o", " -"]
[21.402214, "o", "f "]
[21.492482, "o", "re"]
[21.582638, "o", "ci"]
[21.672609, "o", "pe"]
[21.762748, "o", "-h"]
[21.853045, "o", "el"]
[21.943154, "o", "p/"]
[22.123286, "o", "re"]
[22.2134, "o", "ci"]
[22.303509, "o", "pe"]
[22.393685, "o", "-h"]
[22.483815, "o", "el"]
[22.574005, "o", "p."]
[22.664056, "o", "mk"]
[22.754229, "o", " h"]
[22.844432, "o", "el"]
[23.02464, "o", "p "]
[23.114692, "o", "ba"]
[23.205123, "o", "r\r\n"]
[24.260098, "o", "\u001b[1;36mtask.mk recipe help\u001b[0m\r\n\r\n"]
[24.267129, "o", " \u001b[1;33mbar\u001b[0m\r\n\u001b[38m ─────────────────────────────────────\u001b[0m\r\n @echo 'some rule with no help string'\r\n\r\n"]
[24.271004, "o", "exiting early!\r\n"]
[24.271137, "o", "make[1]: *** [/home/daylin/dev/github/mine/task.mk/task.mk:30: help] Error 1\r\n"]

BIN
docs/examples/recipe-help/demo.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.0 MiB

14
docs/examples/recipe-help/demo.tape Normal file
View File

@ -0,0 +1,14 @@
Output demo.gif
Set FontSize 32
Set Width 1600
Set Height 800
Set Theme "Catppuccin Mocha"
Type "make help" Sleep 1s Enter Sleep 2s
Type "make help help" Sleep 1s Enter Sleep 2s
Type "make help deps-only" Sleep 1s Enter Sleep 2s
Type "make help foo" Sleep 1s Enter Sleep 2s
Type "make help bar" Sleep 1s Enter Sleep 2s
Sleep 2s

10
docs/examples/recipe-help/index.md
View File

@ -1,12 +1,8 @@
---
asciinema: true
---
# Recipe Help
<div id="demo-cast"></div>
![demo](./demo.gif)
```make title="recipe-help.mk"
--8<-- "docs/examples/recipe-help/recipe-help.mk"
```make title="Makefile (recipe-help)"
--8<-- "docs/examples/recipe-help/Makefile"
```

11
docs/examples/recipe-help/record.sh
View File

@ -1,11 +0,0 @@
#!/usr/bin/env bash
source "$(dirname "${BASH_SOURCE[0]}")/../functions.sh"
cmd 'make -f recipe-help/recipe-help.mk help'
cmd 'make -f recipe-help/recipe-help.mk help help'
cmd 'make -f recipe-help/recipe-help.mk help deps-only'
cmd 'make -f recipe-help/recipe-help.mk help foo'
cmd 'make -f recipe-help/recipe-help.mk help bar'
sleep 1

70
docs/index.md
View File

@ -1,9 +1,12 @@
<div align="center">
<h1 align="center"> task.mk </h1>
<img src="https://raw.githubusercontent.com/daylinmorgan/task.mk/main/assets/help.svg" alt="help" width=400 >
<img src="./assets/help.svg" alt="help" width=400 >
<p align="center">
the task runner for GNU Make you've been missing
</p>
<p align="center">
<a href="https://gh.dayl.in/task.mk">Documentation</a>
</p>
</div>
</br>
@ -15,19 +18,25 @@ to add some QOL improvements for your users and fellow maintainers.
Current Features:
- ANSI escape code support (including NO\_COLOR)
- formatted help output
- custom print function
- confirmation prompt
- ANSI escape code support (including NO_COLOR)
- formatted help output
- custom print function
- confirmation prompt
- goal phonifier (disabled by default)
Depends on `GNU Make`, obviously and `Python >=3.7`, and `bash` (or `zsh`).
Wait python?!?!, I'm not `pip` installing some package just to parse my makefile.
I agree, all you need is one file [`.task.mk`](https://github.com/daylinmorgan/task.mk/v23.1.1/task.mk).
You can automagically include it with just two additional lines to your `Makefile` (and probably one to your `.gitignore`) and your good to go.
I agree, all you need is one file [`.task.mk`](./task.mk).
You can automagically include it with just two additional lines to your `Makefile` (and probably one to your `.gitignore`) and you're good to go.
## Setup
One line setup to download .task.mk and add appropriate includes to your `Makefile`.
```bash
bash <(curl -fsSL gh.dayl.in/task.mk/init) # or w/ TASKMK_VERSION=
```
You can include this as an optional dependency on your project by adding the below lines to the end of your `Makefile`.
If someone tries to invoke `make help` it will download `.task.mk` for them.
@ -36,54 +45,11 @@ If someone tries to invoke `make help` it will download `.task.mk` for them.
$(if $(filter help,$(MAKECMDGOALS)),$(if $(wildcard .task.mk),,.task.mk: ; curl -fsSL https://raw.githubusercontent.com/daylinmorgan/task.mk/v23.1.1/task.mk -o .task.mk))
```
You might also consider making it a consistently downloaded dependency if you plan to use any of it's advanced feature set, by dropping the `$(MAKECMDGOALS)` check.
If you plan to use any features besides the help prompt you may want to instead commit `.task.mk` to version control or drop the `$(MAKECMDGOALS)` check so it's always downloaded once `make` is invoked.
```make
-include .task.mk
$(if $(wildcard .task.mk),,.task.mk: ; curl -fsSL https://raw.githubusercontent.com/daylinmorgan/task.mk/v23.1.1/task.mk -o .task.mk)
```
Alternatively, you can use the builtin rule `_update-task.mk` to update to the latest development version.
See [Usage](./usage) to get started running all your tasks.
See [Examples](./examples) for more use cases.
## Zsh Completions for GNU Make
If you use `GNU Make` with zsh you may want to add the following
line to your rc file to allow `make` to handle the autocomplete.
```zsh
zstyle ':completion::complete:make:*:targets' call-command true
```
## Why Make?
There are lot of `GNU Make` alternatives but none have near the same level of ubiquity.
This project attaches to `make` some of the native features of [`just`](https://github.com/casey/just), a command runner.
Just is a great task runner, but it suffers two problems, users probably don't have it installed already, and there is no way to define file specific recipes.
Most of my `Makefile`'s are comprised primarily of handy `.PHONY` recipes, but I always end up with a few file specific recipes.
Another interesting project I've evaluated for these purposes is [`go-task/task`](https://github.com/go-task/task).
`Task` has many of the features of `GNU Make` and some novel features of it's own.
But like `just` it's a tool people don't usually already have and it's configured using a `yaml` file.
`Yaml` files can be finicky to work with and and it uses a golang based shell runtime, not your native shell, which might lead to unexpected behavior.
## Simpler Alternative
But I just want a basic help output, surely I don't need python for this... you would be right.
`Task.mk` replaces my old `make help` recipe boilerplate which may better serve you (so long as you have `sed`/`awk`).
```make
## h, help | show this help
.PHONY: help h
help h: Makefile
@awk -v fill=$(shell sed -n 's/^## \(.*\) | .*/\1/p' $< | wc -L)\
'match($$0,/^## (.*) \|/,name) && match($$0,/\| (.*)$$/,help)\
{printf "\033[1;93m%*s\033[0m | \033[30m%s\033[0m\n",\
fill,name[1],help[1];} match($$0,/^### (.*)/,str) \
{printf "%*s \033[30m%s\033[0m\n",fill," ",str[1];}' $<
```
For more info see the [documentation](https://gh.dayl.in/task.mk).

16
docs/init
View File

@ -11,20 +11,22 @@ if [ -f "./.task.mk" ]; then
fi
curl -fsSL "https://raw.githubusercontent.com/daylinmorgan/task.mk/$VERSION/task.mk" -o .task.mk
echo .task.mk >>.gitignore
printf '\n-include .task.cfg.mk .task.mk\n' >>Makefile
printf '$(if $(filter help,$(MAKECMDGOALS)),$(if $(wildcard .task.mk),,.task.mk: ; curl -fsSL https://raw.githubusercontent.com/daylinmorgan/task.mk/%s/task.mk -o .task.mk))' \
printf '\n-include .task.cfg.mk\n' >>Makefile
printf '%s %s\n' '-include' '.task.mk' >>.task.cfg.mk
printf '$(if $(filter help,$(MAKECMDGOALS)),$(if $(wildcard .task.mk),,.task.mk: ; curl -fsSL https://raw.githubusercontent.com/daylinmorgan/task.mk/%s/task.mk -o .task.mk))\n' \
"$VERSION" \
>>Makefile
>>.task.cfg.mk
printf ".task.mk files added to repo\n\n"
echo "Do you want to commit these changes?"
printf "RUN COMMAND: %s (Y/n) " \
"git add Makefile .gitignore && git commit -m \"chore: initialize .task.mk\""
printf "Run the below command?\n\n %s (Y/n) " \
"git add Makefile .gitignore .task.cfg.mk && git commit -m \"chore: initialize .task.mk\""
read -r answer
read -r answer </dev/tty
# if echo "$answer" | grep -iq "^y" ;then
if [ "$answer" != "${answer#[Yy]}" ]; then
git add Makefile .gitignore && git commit -m "chore: initialize .task.mk"
git add Makefile .gitignore .task.cfg.mk &&
git commit -m "chore: initialize .task.mk"
echo finished.
else
echo finished.

1
docs/javascripts/asciinema-player.min.js vendored
View File

File diff suppressed because one or more lines are too long

16
docs/overrides/main.html
View File

@ -1,16 +0,0 @@
{% extends "base.html" %}
{% block scripts %}
{{ super() }}
{% if page.meta %}
{% if page.meta.asciinema %}
<script async>
AsciinemaPlayer.create('./demo.cast', document.getElementById('demo-cast'),{loop: true});
</script>
{% endif %}
{% endif %}
{% endblock %}

2508
docs/stylesheets/asciinema-player.css
View File

File diff suppressed because it is too large Load Diff

79
docs/usage.md
View File

@ -1,30 +1,71 @@
# Usage
`Task.mk` will add access to a recipe `help` (also aliased to `h`).
In order to use `make help` to you will need to add some custom comments to your `Makefile`.
`Task.mk` can be included in any standard `GNUMakefile`.
If it's been properly sourced you will have access to the below features/recipes.
Deliberately, I don't get names from recipes themselves.
This not only greatly simplifies the parsing but add's some opportunity to customize the output.
Such as to document wildcard or redundant recipes.
See [examples](/task.mk/examples) for more info.
You can place these anywhere, but I recommend adding these notes directly above their relevant recipes.
The format is `## <recipe> | <msg>`
## Builtin Recipes
### Help
Invoked with either `make help` or `make h`.
Adding goals to the builtin help recipe just requires documenting your `Makefile` with comments.
The format is `## <recipe> |> <msg>` or `<recipe>: ## <msg>`
```make
## build | build the project
.PHONY: build
## build |> build the project
build:
...
build: ## build the project
```
Now when you invoke `make help` it will parse these and generate your help output.
In addition you can add raw text to the help output using the format `### <rawmsg>`.
In addition to a generic help output you can expose some configuration settings with `make vars`.
Both recipe documentation and raw messages can be modified with additional arguments delimited by `|>`.
For example:
```make
### build related recipes |> --align center --divider
build: ## build the project |> --msg-style bold
...
package: ## package the project |> -gs b_cyan
```
`Task.mk` can also generate recipe specific help regardless of whether a goal is documented.
This can be invoked by appending the name of a recipe to help call: `make help build`.
All recipes prefixed with and underscore will be hidden even if documented.
However, they can be viewed by invoking `make _help`.
### Vars
In addition to a generic help output you can expose some configuration settings with `make vars` or `make v`.
To do so define the variables you'd like to print with `PRINT_VARS := VAR1 VAR2 VAR3`.
In addition to the `help` and `vars` recipes you can use a custom make function to format your text for fancier output.
For this there are two options depending on your needs `tprint` or `tprint-sh`. (`tprint-sh` is for use within a multiline sub-shell that has already been silenced, see the version-check rule of this project's `Makefile` for an example.)
## Builtin Functions
### Phonify
Phonify is a new experimental feature of `task.mk` that solves one of the biggest gotchas of using `make` as a task runner!
It stands to reason the tasks you document are likely to all be phony recipes
Rather than write `.PHONY: <goal>` repeatedly, simply enable `task.mk`'s phonifier.
`Task.mk` will then parse your `Makefile` for documented tasks and
generate the necessary `.PHONY: <recipes>` line to ensure they are always executed.
To use this feature set the `PHONIFY` environment variable before including `.task.mk`.
To avoid adding a documented task/recipe to `.PHONY`, use `|> --not-phony` after the recipe message.
### Tprint
Besides the `help` and `vars` recipes you can use a custom make function to format your text for fancier output.
For this there are two options depending on your needs `tprint` or `tprint-verbose`
(`tprint-verbose` is for use within a multiline sub-shell that has already been silenced,
see the version-check rule of this project's `Makefile` for an example).
To use `tprint` you call it with the builtin `make` call function.
It accepts only one argument: an unquoted f-string literal.
@ -32,20 +73,17 @@ All strings passed to `tprint` have access to an object `ansi` or `a` for simpli
This stores ANSI escape codes which can be used to style your text.
```make
## build | compile the source
.PHONY: build
build:
build: ## compile the source
$(call tprint,{a.cyan}Build Starting{a.end})
...
$(call tprint,{a.green}Build Finished{a.end})
```
See this projects `make info` for more examples of `tprint`.
To see the available colors and formatting(bold,italic,etc.) use the hidden recipe `make _print-ansi`.
**Note**: Any help commands starting with an underscore will be ignored.
To view hidden `tasks` (or recipes in GNU Make land) you can use `make _help`.
In addition, you can use custom colors using the builtin `ansi.custom` or (`a.custom`) method.
It has two optional arguments `fg` and `bg`. Which can be used to specify either an 8-bit color from the [256 colors](https://en.wikipedia.org/wiki/8-bit_color).
Or a tuple/list to define an RBG 24-bit color, for instance `a.custom(fg=(5,10,255))`.
@ -54,7 +92,7 @@ See this project's `make info` for an example.
## Configuration
You can quickly customize some of the default behavior of `task.mk` by overriding the below variables prior to the `-include .task.mk`.
These can also be included in a seperate file `.task.cfg.mk`.
These can also for instance included in a seperate file `.task.cfg.mk`.
```make
# ---- [config] ---- #
@ -69,7 +107,8 @@ HELP_SEP ?= │
# python f-string literals
EPILOG ?=
USAGE ?={ansi.$(HEADER_STYLE)}usage{ansi.end}:\n make <recipe>\n
INHERIT_SHELL ?=
TASKMK_SHELL ?=
PHONIFY ?=
```
To use a custom color for one of the predefined configuration variables specify only the custom method.
@ -80,7 +119,7 @@ HEADER_STYLE = custom(fg=171,bg=227)
**NOTE**: `HELP_SEP` does not change the argument definitions syntax only the format of `make help`.
## Advanced Usage: Embedded Python Scripts
## Advanced Usage: Embedded Scripts
You can take advantage of the builtin python script runner and write multi-line python scripts of your own.
This is a simple example but a few lines of python in your `Makefile`

5
mkdocs.yml
View File

@ -3,18 +3,15 @@ site_url: https://gh.dayl.in/task.mk
repo_url: https://github.com/daylinmorgan/task.mk
edit_uri: edit/main/docs/
repo_name: daylinmorgan/task.mk
theme:
name: material
custom_dir: docs/overrides
features:
- navigation.indexes
palette:
- scheme: default
extra_css:
- stylesheets/extra.css
- stylesheets/asciinema-player.css
extra_javascript:
- javascripts/asciinema-player.min.js
plugins:
- search
- git-revision-date-localized:

2
src/config.mk
View File

@ -11,4 +11,4 @@ WRAP ?= 100
# python f-string literals
EPILOG ?=
USAGE ?={ansi.header}usage{ansi.end}:\n make <recipe>\n
INHERIT_SHELL ?=
PHONIFY ?=

15
task.mk
View File

@ -1,7 +1,7 @@
# }> [github.com/daylinmorgan/task.mk] <{ #
# Copyright (c) 2022 Daylin Morgan
# MIT License
TASKMK_VERSION ?= v23.1.1-12-gb0f7493-dev
TASKMK_VERSION ?= v23.1.1-18-g1b8bdaa-dev
# task.mk should be included at the bottom of your Makefile with `-include .task.mk`
# See below for the standard configuration options that should be set prior to including this file.
# You can update your .task.mk with `make _update-task.mk`
@ -19,10 +19,12 @@ WRAP ?= 100
# python f-string literals
EPILOG ?=
USAGE ?={ansi.header}usage{ansi.end}:\n make <recipe>\n
INHERIT_SHELL ?=
TASKMK_SHELL ?=
PHONIFY ?=
# ---- [python scripts] ---- #
define help_py
from collections import namedtuple
from pathlib import Path
import subprocess
from textwrap import wrap
$(utils_py)
@ -46,10 +48,14 @@ def recipe_help_header(goal):
)
else:
return f" {ansi.style(goal,'goal')}"
def get_makefile_list():
pattern = re.compile(r'^\.?task.*?\.mk$$')
makefiles = os.getenv("MAKEFILE_LIST", "").split()
return (f for f in makefiles if not pattern.match(Path(f).name))
def get_goal_deps(goal="task.mk"):
make = os.getenv("MAKE", "make")
cmd = [make, "-p", "-n", "-i"]
for file in os.getenv("TASK_MAKEFILE_LIST", "").split():
for file in get_makefile_list():
cmd.extend(["-f", file])
database = subprocess.check_output(cmd, universal_newlines=True)
dep_pattern = re.compile(r"^" + goal + ":(.*)?")
@ -450,8 +456,7 @@ tprint = $(call py,print_py,$(1))
tprint-verbose= $(call py-verbose,print_py,$(1))
tconfirm = $(call py,confirm_py,$(1))
.PHONY: h help _help _print-ansi _update-task.mk
TASK_MAKEFILE_LIST := $(filter-out .task.cfg.mk .task.mk,$(MAKEFILE_LIST))
export MAKEFILE_LIST MAKE TASK_MAKEFILE_LIST
export MAKEFILE_LIST MAKE
ifdef PHONIFY
$(shell MAKEFILE_LIST='$(MAKEFILE_LIST)' $(call py-verbose,phonify_py))
endif