From 5ff0426480bf2fe4fd4d3ded55f70b2e311a333b Mon Sep 17 00:00:00 2001 From: <> Date: Sat, 24 Sep 2022 22:56:44 +0000 Subject: [PATCH] Deployed b19ddba with MkDocs version: 1.3.1 --- 404.html | 45 +++ examples/Makefile | 2 +- examples/check/demo.cast | 213 ++++------ examples/check/index.html | 45 +++ examples/embedded/demo.cast | 209 ++++------ examples/embedded/index.html | 60 +++ examples/embedded/record.sh | 1 + examples/functions.sh | 2 +- examples/index.html | 55 ++- examples/recipe-help/demo.cast | 138 +++++++ examples/recipe-help/index.html | 596 ++++++++++++++++++++++++++++ examples/recipe-help/recipe-help.mk | 24 ++ examples/recipe-help/record.sh | 11 + index.html | 45 +++ search/search_index.json | 2 +- sitemap.xml | 15 +- sitemap.xml.gz | Bin 240 -> 250 bytes usage/index.html | 45 +++ 18 files changed, 1242 insertions(+), 266 deletions(-) create mode 100644 examples/recipe-help/demo.cast create mode 100644 examples/recipe-help/index.html create mode 100644 examples/recipe-help/recipe-help.mk create mode 100644 examples/recipe-help/record.sh diff --git a/404.html b/404.html index 717449c..0fd6e56 100644 --- a/404.html +++ b/404.html @@ -263,6 +263,8 @@ + + @@ -371,6 +373,49 @@ + + + + + + +
  • + + + + + + + + + + + + + + + +
    + Recipe help + +
    + + +
    • + + + + diff --git a/examples/Makefile b/examples/Makefile index 425a1d7..3c0f669 100644 --- a/examples/Makefile +++ b/examples/Makefile @@ -1,7 +1,7 @@ MAKEFLAGS += --no-print-directory COLS ?= 60 ROWS ?= 20 -EXAMPLES := check embedded +EXAMPLES := check embedded recipe-help CASTS := $(addsuffix /demo.cast, $(EXAMPLES)) all: $(CASTS) diff --git a/examples/check/demo.cast b/examples/check/demo.cast index 85d9923..9c5b55f 100644 --- a/examples/check/demo.cast +++ b/examples/check/demo.cast @@ -1,129 +1,84 @@ -{"version": 2, "width": 48, "height": 12, "timestamp": 1663712361, "env": {"SHELL": "/usr/bin/zsh", "TERM": "xterm-256color"}} -[0.008114, "o", "\u001b[H\u001b[2J\u001b[3J"] -[0.00852, "o", "bash >> "] -[0.008755, "o", "m"] -[0.189398, "o", "a"] -[0.279744, "o", "k"] -[0.369775, "o", "e"] -[0.459919, "o", " -"] -[0.549908, "o", "f"] -[0.639982, "o", " "] -[0.730339, "o", "c"] -[0.820338, "o", "h"] -[0.910414, "o", "ec"] -[1.090651, "o", "k"] -[1.18077, "o", "/"] -[1.271098, "o", "c"] -[1.361098, "o", "h"] -[1.451216, "o", "ec"] -[1.541276, "o", "k"] -[1.631388, "o", "."] -[1.721603, "o", "m"] -[1.811718, "o", "k"] -[1.992079, "o", " h"] -[2.082138, "o", "e"] -[2.172379, "o", "l"] -[2.262403, "o", "p"] -[2.352473, "o", "\r\n"] -[3.381969, "o", "\u001b[1;36musage:\u001b[0m\r\n\tmake \r\n\t\r\n\tinteractivity w/ task.mk\r\n\r\n\u001b[1;33m check\u001b[0m │ \u001b[2mget user confirmation or exit\u001b[0m\r\n\u001b[1;33m h, help\u001b[0m │ \u001b[2mshow this help\u001b[0m\r\n\r\n"] -[5.387545, "o", "\u001b[H\u001b[2J\u001b[3J"] -[5.387892, "o", "bash >> "] -[5.390047, "o", "m"] -[5.570645, "o", "a"] -[5.660579, "o", "k"] -[5.750852, "o", "e"] -[5.841071, "o", " -"] -[5.931225, "o", "f"] -[6.021286, "o", " "] -[6.111373, "o", "c"] -[6.201586, "o", "h"] -[6.291778, "o", "ec"] -[6.472054, "o", "k"] -[6.562124, "o", "/"] -[6.652262, "o", "c"] -[6.74248, "o", "h"] -[6.832675, "o", "ec"] -[6.922668, "o", "k"] -[7.012809, "o", "."] -[7.102973, "o", "m"] -[7.193151, "o", "k"] -[7.373458, "o", " c"] -[7.463783, "o", "h"] -[7.553761, "o", "e"] -[7.643931, "o", "c"] -[7.734197, "o", "k"] -[7.824356, "o", "\r\n"] -[8.857505, "o", "Would you like to proceed? \u001b[1;31m[Y/n]\u001b[0m "] -[9.54018, "o", "y"] -[9.595198, "o", "\r\n"] -[9.598684, "o", "you said yes!\r\n"] -[11.602689, "o", "#"] -[11.783071, "o", " "] -[11.873235, "o", "L"] -[11.963465, "o", "e"] -[12.053444, "o", "t'"] -[12.143548, "o", "s"] -[12.233881, "o", " "] -[12.323915, "o", "t"] -[12.41414, "o", "r"] -[12.50428, "o", "y "] -[12.684471, "o", "a"] -[12.774773, "o", "g"] -[12.864864, "o", "a"] -[12.954989, "o", "i"] -[13.045011, "o", "n "] -[13.135204, "o", "b"] -[13.225451, "o", "u"] -[13.315649, "o", "t"] -[13.405687, "o", " "] -[13.585943, "o", "in"] -[13.676051, "o", "s"] -[13.766346, "o", "t"] -[13.856324, "o", "e"] -[13.946542, "o", "a"] -[14.036697, "o", "d "] -[14.126782, "o", "s"] -[14.216944, "o", "a"] -[14.307128, "o", "y"] -[14.487468, "o", " "] -[14.577551, "o", "no"] -[14.667739, "o", " "] -[14.757899, "o", "t"] -[14.848007, "o", "h"] -[14.93806, "o", "i"] -[15.0283, "o", "s "] -[15.118379, "o", "t"] -[15.208471, "o", "i"] -[15.388757, "o", "m"] -[15.47897, "o", "e"] -[15.569031, "o", "\r\n"] -[16.571969, "o", "\u001b[H\u001b[2J\u001b[3J"] -[16.572047, "o", "bash >> "] -[16.574017, "o", "m"] -[16.754499, "o", "a"] -[16.844612, "o", "k"] -[16.93468, "o", "e"] -[17.024972, "o", " -"] -[17.115137, "o", "f"] -[17.205244, "o", " "] -[17.295415, "o", "c"] -[17.385554, "o", "h"] -[17.475882, "o", "ec"] -[17.655989, "o", "k"] -[17.746279, "o", "/"] -[17.83643, "o", "c"] -[17.926644, "o", "h"] -[18.016673, "o", "ec"] -[18.106718, "o", "k"] -[18.197045, "o", "."] -[18.287031, "o", "m"] -[18.377151, "o", "k"] -[18.55735, "o", " c"] -[18.647478, "o", "h"] -[18.737616, "o", "e"] -[18.827879, "o", "c"] -[18.917992, "o", "k"] -[19.008133, "o", "\r\n"] -[20.034923, "o", "Would you like to proceed? \u001b[1;31m[Y/n]\u001b[0m "] -[22.08808, "o", "n"] -[22.227223, "o", "\r\n"] +{"version": 2, "width": 48, "height": 12, "timestamp": 1664060067, "env": {"SHELL": "/usr/bin/zsh", "TERM": "xterm-256color"}} +[0.008028, "o", "\u001b[H\u001b[2J\u001b[3J"] +[0.008412, "o", "bash >> "] +[0.008649, "o", "ma"] +[0.189116, "o", "ke"] +[0.279092, "o", " -"] +[0.369181, "o", "f "] +[0.459296, "o", "ch"] +[0.549434, "o", "ec"] +[0.639704, "o", "k/"] +[0.729786, "o", "ch"] +[0.81994, "o", "ec"] +[0.910178, "o", "k."] +[1.090415, "o", "mk"] +[1.180666, "o", " h"] +[1.270767, "o", "el"] +[1.360807, "o", "p\r\n"] +[2.392643, "o", "\u001b[1;36musage:\u001b[0m\r\n\tmake \r\n\t\r\n\tinteractivity w/ task.mk\r\n\r\n\u001b[1;33m check\u001b[0m │ \u001b[2mget user confirmation or exit\u001b[0m\r\n\u001b[1;33m h, help\u001b[0m │ \u001b[2mshow this help\u001b[0m\r\n\r\n"] +[4.398843, "o", "\u001b[H\u001b[2J\u001b[3J"] +[4.398948, "o", "bash >> "] +[4.399576, "o", "ma"] +[4.580421, "o", "ke"] +[4.670533, "o", " -"] +[4.760674, "o", "f "] +[4.850908, "o", "ch"] +[4.940859, "o", "ec"] +[5.031095, "o", "k/"] +[5.121228, "o", "ch"] +[5.211271, "o", "ec"] +[5.301383, "o", "k."] +[5.481587, "o", "mk"] +[5.571714, "o", " c"] +[5.662002, "o", "he"] +[5.752104, "o", "ck"] +[5.842305, "o", "\r\n"] +[6.864798, "o", "Would you like to proceed? \u001b[1;31m[Y/n]\u001b[0m "] +[7.488194, "o", "y"] +[7.830894, "o", "\r\n"] +[7.836313, "o", "you said yes!\r\n"] +[9.840217, "o", "# "] +[10.020704, "o", "Le"] +[10.110897, "o", "t'"] +[10.201077, "o", "s "] +[10.291171, "o", "tr"] +[10.381382, "o", "y "] +[10.471532, "o", "ag"] +[10.5617, "o", "ai"] +[10.651984, "o", "n "] +[10.742177, "o", "bu"] +[10.922348, "o", "t "] +[11.012569, "o", "in"] +[11.102605, "o", "st"] +[11.192785, "o", "ea"] +[11.282913, "o", "d "] +[11.373109, "o", "sa"] +[11.463146, "o", "y "] +[11.553266, "o", "no"] +[11.6436, "o", " t"] +[11.823731, "o", "hi"] +[11.913841, "o", "s "] +[12.003886, "o", "ti"] +[12.094101, "o", "me"] +[12.184197, "o", "\r\n"] +[13.185929, "o", "\u001b[H\u001b[2J\u001b[3J"] +[13.185977, "o", "bash >> "] +[13.186676, "o", "ma"] +[13.367108, "o", "ke"] +[13.457234, "o", " -"] +[13.547276, "o", "f "] +[13.637696, "o", "ch"] +[13.727919, "o", "ec"] +[13.817921, "o", "k/"] +[13.908217, "o", "ch"] +[13.998375, "o", "ec"] +[14.08855, "o", "k."] +[14.268802, "o", "mk"] +[14.359106, "o", " c"] +[14.449085, "o", "he"] +[14.539194, "o", "ck"] +[14.629387, "o", "\r\n"] +[15.652945, "o", "Would you like to proceed? \u001b[1;31m[Y/n]\u001b[0m "] +[16.544875, "o", "n"] +[17.098374, "o", "\r\n"] +[17.103306, "o", "make[1]: *** [check/check.mk:4: check] Error 1\r\n"] diff --git a/examples/check/index.html b/examples/check/index.html index d1710fa..8a7694c 100644 --- a/examples/check/index.html +++ b/examples/check/index.html @@ -272,6 +272,8 @@ + + @@ -382,6 +384,49 @@ + + + + + + +
  • + + + + + + + + + + + + + + + +
    + Recipe help + +
    + + +
    • + + + + diff --git a/examples/embedded/demo.cast b/examples/embedded/demo.cast index 6d5235c..48c2967 100644 --- a/examples/embedded/demo.cast +++ b/examples/embedded/demo.cast @@ -1,126 +1,83 @@ -{"version": 2, "width": 60, "height": 20, "timestamp": 1663712193, "env": {"SHELL": "/usr/bin/zsh", "TERM": "xterm-256color"}} -[0.008386, "o", "\u001b[H\u001b[2J\u001b[3J"] -[0.008986, "o", "bash >> "] -[0.009151, "o", "m"] -[0.189701, "o", "a"] -[0.280162, "o", "k"] -[0.37038, "o", "e"] -[0.460683, "o", " -"] -[0.551001, "o", "f"] -[0.641267, "o", " "] -[0.731609, "o", "e"] -[0.821777, "o", "m"] -[0.912103, "o", "be"] -[1.092658, "o", "d"] -[1.182705, "o", "d"] -[1.273152, "o", "e"] -[1.363457, "o", "d"] -[1.453758, "o", "/e"] -[1.544059, "o", "m"] -[1.634282, "o", "b"] -[1.724452, "o", "e"] -[1.814601, "o", "d"] -[1.995155, "o", "de"] -[2.085437, "o", "d"] -[2.175546, "o", "."] -[2.265856, "o", "m"] -[2.356192, "o", "k"] -[2.446468, "o", " h"] -[2.536781, "o", "e"] -[2.627101, "o", "l"] -[2.717423, "o", "p"] -[2.897934, "o", "\r\n"] -[3.931131, "o", "\u001b[1;36musage:\u001b[0m\r\n\tmake \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"] -[5.936874, "o", "\u001b[H\u001b[2J\u001b[3J"] -[5.937167, "o", "bash >> "] -[5.939502, "o", "m"] -[6.120169, "o", "a"] -[6.210505, "o", "k"] -[6.300671, "o", "e"] -[6.390788, "o", " -"] -[6.480981, "o", "f"] -[6.571285, "o", " "] -[6.661457, "o", "e"] -[6.751758, "o", "m"] -[6.842048, "o", "be"] -[7.022576, "o", "d"] -[7.112852, "o", "d"] -[7.203064, "o", "e"] -[7.293421, "o", "d"] -[7.383397, "o", "/e"] -[7.473873, "o", "m"] -[7.564152, "o", "b"] -[7.65431, "o", "e"] -[7.744607, "o", "d"] -[7.925168, "o", "de"] -[8.015472, "o", "d"] -[8.105767, "o", "."] -[8.195936, "o", "m"] -[8.286184, "o", "k"] -[8.376537, "o", " l"] -[8.466624, "o", "i"] -[8.557058, "o", "s"] -[8.64739, "o", "t"] -[8.827942, "o", "-"] -[8.91803, "o", "em"] -[9.008446, "o", "b"] -[9.098742, "o", "e"] -[9.189059, "o", "d"] -[9.279328, "o", "d"] -[9.36965, "o", "ed"] -[9.459574, "o", "\r\n"] -[10.492826, "o", "files in embedded\r\n"] -[10.492943, "o", "['embedded.mk', 'demo.cast', 'record.sh', 'index.md']\r\n"] -[12.498865, "o", "\u001b[H\u001b[2J\u001b[3J"] -[12.498984, "o", "bash >> "] -[12.501382, "o", "m"] -[12.681906, "o", "a"] -[12.7722, "o", "k"] -[12.862501, "o", "e"] -[12.952783, "o", " -"] -[13.043086, "o", "f"] -[13.13339, "o", " "] -[13.223546, "o", "e"] -[13.313887, "o", "m"] -[13.40413, "o", "be"] -[13.584464, "o", "d"] -[13.674721, "o", "d"] -[13.764931, "o", "e"] -[13.855143, "o", "d"] -[13.945476, "o", "/e"] -[14.035801, "o", "m"] -[14.126086, "o", "b"] -[14.216402, "o", "e"] -[14.306688, "o", "d"] -[14.487263, "o", "de"] -[14.577566, "o", "d"] -[14.667572, "o", "."] -[14.757974, "o", "m"] -[14.848201, "o", "k"] -[14.938383, "o", " e"] -[15.02867, "o", "m"] -[15.118961, "o", "b"] -[15.2091, "o", "e"] -[15.38968, "o", "d"] -[15.479924, "o", "de"] -[15.570276, "o", "d"] -[15.66027, "o", "-"] -[15.750729, "o", "b"] -[15.84091, "o", "a"] -[15.931277, "o", "sh"] -[16.021429, "o", "\r\n"] -[17.044626, "o", "Is the process running bash? We can check with ps\r\n"] -[17.063304, "o", "bash\r\n"] -[17.063756, "o", "What text to figlet? \r\n"] -[20.107984, "o", "t"] -[20.125262, "o", "a"] -[20.276406, "o", "s"] -[20.454083, "o", "k"] -[20.705234, "o", "."] -[20.931947, "o", "m"] -[21.010096, "o", "k"] -[21.288327, "o", "\r\n"] -[21.292384, "o", " _ _ _ \r\n| |_ __ _ ___| | __ _ __ ___ | | __\r\n| __/ _` / __| |/ / | '_ ` _ \\| |/ /\r\n| || (_| \\__ \\ < _| | | | | | < \r\n \\__\\__,_|___/_|\\_(_)_| |_| |_|_|\\_\\\r\n \r\n"] -[21.292754, "o", "the argument below as given in the makefile itself\r\n"] -[21.292898, "o", "it's expanded before the script is passed to bash\r\n"] -[21.292925, "o", "bash multiline is probably working\r\n"] +{"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 \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"] diff --git a/examples/embedded/index.html b/examples/embedded/index.html index 509a0c0..aa57574 100644 --- a/examples/embedded/index.html +++ b/examples/embedded/index.html @@ -272,6 +272,8 @@ + + @@ -382,6 +384,49 @@ + + + + + + +
  • + + + + + + + + + + + + + + + +
    + Recipe help + +
    + + +
    • + + + + @@ -522,6 +567,21 @@ + + +
    diff --git a/examples/embedded/record.sh b/examples/embedded/record.sh index af74c1b..cdfc42e 100644 --- a/examples/embedded/record.sh +++ b/examples/embedded/record.sh @@ -5,4 +5,5 @@ 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 diff --git a/examples/functions.sh b/examples/functions.sh index 733a0ad..25436e7 100644 --- a/examples/functions.sh +++ b/examples/functions.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash msg() { - printf '%s\n' "$1" | pv -qL 12 + printf '%s\n' "$1" | pv -qL 20 sleep 1 } diff --git a/examples/index.html b/examples/index.html index ae7948d..543a6e7 100644 --- a/examples/index.html +++ b/examples/index.html @@ -272,6 +272,8 @@ + + @@ -380,6 +382,49 @@ + + + + + + +
  • + + + + + + + + + + + + + + + +
    + Recipe help + +
    + + +
    • + + + + @@ -426,14 +471,18 @@

    Examples

    -
    Check
    +
    Confirm

    Perform a basic confirmation test with the user and exit with error code 1 if input is N/n.

    -
    Embedded
    +
    Embedded Scripts

    Use the builtin functions to write multi-line python/bash scripts directly in your Makefile

    +
    Recipe Help
    +
    +

    Display the target, docstring and recipe for a given target then exit.

    +
    @@ -441,7 +490,7 @@ Last update: - September 18, 2022 + September 24, 2022
    Created: diff --git a/examples/recipe-help/demo.cast b/examples/recipe-help/demo.cast new file mode 100644 index 0000000..251e71f --- /dev/null +++ b/examples/recipe-help/demo.cast @@ -0,0 +1,138 @@ +{"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 \r\n\tmake help \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"] diff --git a/examples/recipe-help/index.html b/examples/recipe-help/index.html new file mode 100644 index 0000000..7c4e517 --- /dev/null +++ b/examples/recipe-help/index.html @@ -0,0 +1,596 @@ + + + + + + + + + + + + + + + + + + Recipe Help - task.mk + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + +
    + + +
    + +
    + + + + + + +
    +
    + + + +
    +
    +
    + + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    +
    + + + +
    +
    + + + + + + + + + +

    Recipe Help

    +
    + +
    recipe-help.mk
    ## deps-only | a task/target with dependencies
+.PHONY: deps-only
+deps-only: foo
+
+## foo | a dummy rule that depends on the local files
+.PHONY: foo
+foo: $(wildcard *)
+    @echo 'this is a dummy rule'
+
+# bar but no docstring
+.PHONY: bar
+bar:
+    @echo 'some rule with no help string'
+
+define USAGE
+{a.header}usage:{a.end}
+    make <recipe>
+    make help <recipe>
+
+endef
+
+.DEFAULT_GOAL = help
+include $(shell git rev-parse --show-toplevel)/task.mk
+
    + +
    +
    + + + Last update: + September 24, 2022 + +
    + Created: + September 24, 2022 + + +     +
    + + + + + + +
    +
    + + +
    + +
    + + + +
    +
    +
    +
    + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/examples/recipe-help/recipe-help.mk b/examples/recipe-help/recipe-help.mk new file mode 100644 index 0000000..1f50dbf --- /dev/null +++ b/examples/recipe-help/recipe-help.mk @@ -0,0 +1,24 @@ +## deps-only | a task/target with dependencies +.PHONY: deps-only +deps-only: foo + +## foo | a dummy rule that depends on the local files +.PHONY: foo +foo: $(wildcard *) + @echo 'this is a dummy rule' + +# bar but no docstring +.PHONY: bar +bar: + @echo 'some rule with no help string' + +define USAGE +{a.header}usage:{a.end} + make + make help + +endef + +.DEFAULT_GOAL = help +include $(shell git rev-parse --show-toplevel)/task.mk + diff --git a/examples/recipe-help/record.sh b/examples/recipe-help/record.sh new file mode 100644 index 0000000..0ce5a85 --- /dev/null +++ b/examples/recipe-help/record.sh @@ -0,0 +1,11 @@ +#!/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 diff --git a/index.html b/index.html index faf7103..f8c5dbd 100644 --- a/index.html +++ b/index.html @@ -328,6 +328,8 @@ + + @@ -436,6 +438,49 @@ + + + + + + +
  • + + + + + + + + + + + + + + + +
    + Recipe help + +
    + + +
    • + + + + diff --git a/search/search_index.json b/search/search_index.json index 503991a..3076e0c 100644 --- a/search/search_index.json +++ b/search/search_index.json @@ -1 +1 @@ -{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"task.mk the task runner for GNU Make you've been missing GNU make is an excellent build tool and the task runner we love to hate, but can't escape. So let's improve the UX to make it the best task runner it can be. Task.mk , is a standalone Makefile you can deploy alongside your own 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 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 . You can automagically include it with just two additional lines to your Makefile (and probably one to your .gitignore ) and your good to go. Setup 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. -include .task.mk $(if $(filter help,$(MAKECMDGOALS)),$(if $(wildcard .task.mk),,.task.mk : ; curl - fsSL https :// raw . githubusercontent . com / daylinmorgan / task . mk / v 22.9.19/ 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. -include .task.mk $(if $(wildcard .task.mk),,.task.mk : ; curl - fsSL https :// raw . githubusercontent . com / daylinmorgan / task . mk / v 22.9.19/ task . mk - o . task . mk ) Alternatively, you can use the builtin rule _update-task.mk to update to the latest development version. See Usage to get started running all your tasks. See 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. 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 , 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 . 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 ). ## 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];}' $<","title":"Home"},{"location":"#setup","text":"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. -include .task.mk $(if $(filter help,$(MAKECMDGOALS)),$(if $(wildcard .task.mk),,.task.mk : ; curl - fsSL https :// raw . githubusercontent . com / daylinmorgan / task . mk / v 22.9.19/ 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. -include .task.mk $(if $(wildcard .task.mk),,.task.mk : ; curl - fsSL https :// raw . githubusercontent . com / daylinmorgan / task . mk / v 22.9.19/ task . mk - o . task . mk ) Alternatively, you can use the builtin rule _update-task.mk to update to the latest development version. See Usage to get started running all your tasks. See Examples for more use cases.","title":"Setup"},{"location":"#zsh-completions-for-gnu-make","text":"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. zstyle ':completion::complete:make:*:targets' call-command true","title":"Zsh Completions for GNU Make"},{"location":"#why-make","text":"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 , 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 . 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.","title":"Why Make?"},{"location":"#simpler-alternative","text":"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 ). ## 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];}' $<","title":"Simpler Alternative"},{"location":"usage/","text":"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 . 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. You can place these anywhere, but I recommend adding these notes directly above their relevant recipes. The format is ## | ## build | build the project .PHONY : build build : ... Now when you invoke make help it will parse these and generate your help output. In addition to a generic help output you can expose some configuration settings with make vars . 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.) To use tprint you call it with the builtin make call function. It accepts only one argument: an unquoted f-string literal. All strings passed to tprint have access to an object ansi or a for simplicity. This stores ANSI escape codes which can be used to style your text. ## build | compile the source .PHONY : build build : $( 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 . Or a tuple/list to define an RBG 24-bit color, for instance a.custom(fg=(5,10,255)) . 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 . # ---- [config] ---- # HEADER_STYLE ?= b_cyan ACCENT_STYLE ?= b_yellow PARAMS_STYLE ?= $( ACCENT_STYLE ) GOAL_STYLE ?= $( ACCENT_STYLE ) MSG_STYLE ?= faint DIVIDER_STYLE ?= default DIVIDER ?= \u2500 HELP_SEP ?= \u2502 # python f-string literals EPILOG ?= USAGE ?={ ansi. $( HEADER_STYLE ) } usage { ansi.end } : \\n make \\n INHERIT_SHELL ?= To use a custom color for one of the predefined configuration variables specify only the custom method. 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 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 may be easier than balancing sub-shells and strung together awk commands. When make expands the function it will take the parameters passed to py and expand them. $(1) is the variable name and $(2) in this case is the implicit pattern from the rule. Pay attention to quotes. If you need to debug your python script, use DEBUG=1 when you run make and it will first print the script that will be piped to python . 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 list-% : $( call py,list_files_py, $* ) For what it's worth there is also a predefined function for bash (named tbash ) as well should you need to accomplish something similar of more easily embedding your bash script rather than having to escape every line with a backslash. define bash_script figlet task.mk 2>/dev/null || echo 'no figlet : (' echo \"This is from bash\" cat /etc/hostname printf \"%s\\n\" \"$(2)\" endef .PHONY : test - bash test-bash : $( call tbash,bash_script,test bash multiline )","title":"Usage"},{"location":"usage/#usage","text":"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 . 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. You can place these anywhere, but I recommend adding these notes directly above their relevant recipes. The format is ## | ## build | build the project .PHONY : build build : ... Now when you invoke make help it will parse these and generate your help output. In addition to a generic help output you can expose some configuration settings with make vars . 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.) To use tprint you call it with the builtin make call function. It accepts only one argument: an unquoted f-string literal. All strings passed to tprint have access to an object ansi or a for simplicity. This stores ANSI escape codes which can be used to style your text. ## build | compile the source .PHONY : build build : $( 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 . Or a tuple/list to define an RBG 24-bit color, for instance a.custom(fg=(5,10,255)) . See this project's make info for an example.","title":"Usage"},{"location":"usage/#configuration","text":"You can quickly customize some of the default behavior of task.mk by overriding the below variables prior to the -include .task.mk . # ---- [config] ---- # HEADER_STYLE ?= b_cyan ACCENT_STYLE ?= b_yellow PARAMS_STYLE ?= $( ACCENT_STYLE ) GOAL_STYLE ?= $( ACCENT_STYLE ) MSG_STYLE ?= faint DIVIDER_STYLE ?= default DIVIDER ?= \u2500 HELP_SEP ?= \u2502 # python f-string literals EPILOG ?= USAGE ?={ ansi. $( HEADER_STYLE ) } usage { ansi.end } : \\n make \\n INHERIT_SHELL ?= To use a custom color for one of the predefined configuration variables specify only the custom method. HEADER_STYLE = custom ( fg = 171 ,bg = 227 ) NOTE : HELP_SEP does not change the argument definitions syntax only the format of make help .","title":"Configuration"},{"location":"usage/#advanced-usage-embedded-python-scripts","text":"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 may be easier than balancing sub-shells and strung together awk commands. When make expands the function it will take the parameters passed to py and expand them. $(1) is the variable name and $(2) in this case is the implicit pattern from the rule. Pay attention to quotes. If you need to debug your python script, use DEBUG=1 when you run make and it will first print the script that will be piped to python . 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 list-% : $( call py,list_files_py, $* ) For what it's worth there is also a predefined function for bash (named tbash ) as well should you need to accomplish something similar of more easily embedding your bash script rather than having to escape every line with a backslash. define bash_script figlet task.mk 2>/dev/null || echo 'no figlet : (' echo \"This is from bash\" cat /etc/hostname printf \"%s\\n\" \"$(2)\" endef .PHONY : test - bash test-bash : $( call tbash,bash_script,test bash multiline )","title":"Advanced Usage: Embedded Python Scripts"},{"location":"examples/","text":"Examples Check Perform a basic confirmation test with the user and exit with error code 1 if input is N/n. Embedded Use the builtin functions to write multi-line python/bash scripts directly in your Makefile","title":"Examples"},{"location":"examples/#examples","text":"Check Perform a basic confirmation test with the user and exit with error code 1 if input is N/n. Embedded Use the builtin functions to write multi-line python/bash scripts directly in your Makefile","title":"Examples"},{"location":"examples/check/","text":"Check check.mk ## 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 interactivity w/ task.mk \\n endef .DEFAULT_GOAL = help include $(shell git rev-parse --show-toplevel)/task.mk","title":"Check"},{"location":"examples/check/#check","text":"check.mk ## 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 interactivity w/ task.mk \\n endef .DEFAULT_GOAL = help include $(shell git rev-parse --show-toplevel)/task.mk","title":"Check"},{"location":"examples/embedded/","text":"Embedded embedded.mk ### 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 examples of embedded scripts in ` { a.magenta } Makefile { a.end } ` endef .DEFAULT_GOAL = help include $(shell git rev-parse --show-toplevel)/task.mk","title":"Embedded"},{"location":"examples/embedded/#embedded","text":"embedded.mk ### 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 examples of embedded scripts in ` { a.magenta } Makefile { a.end } ` endef .DEFAULT_GOAL = help include $(shell git rev-parse --show-toplevel)/task.mk","title":"Embedded"}]} \ No newline at end of file +{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"task.mk the task runner for GNU Make you've been missing GNU make is an excellent build tool and the task runner we love to hate, but can't escape. So let's improve the UX to make it the best task runner it can be. Task.mk , is a standalone Makefile you can deploy alongside your own 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 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 . You can automagically include it with just two additional lines to your Makefile (and probably one to your .gitignore ) and your good to go. Setup 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. -include .task.mk $(if $(filter help,$(MAKECMDGOALS)),$(if $(wildcard .task.mk),,.task.mk : ; curl - fsSL https :// raw . githubusercontent . com / daylinmorgan / task . mk / v 22.9.19/ 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. -include .task.mk $(if $(wildcard .task.mk),,.task.mk : ; curl - fsSL https :// raw . githubusercontent . com / daylinmorgan / task . mk / v 22.9.19/ task . mk - o . task . mk ) Alternatively, you can use the builtin rule _update-task.mk to update to the latest development version. See Usage to get started running all your tasks. See 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. 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 , 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 . 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 ). ## 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];}' $<","title":"Home"},{"location":"#setup","text":"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. -include .task.mk $(if $(filter help,$(MAKECMDGOALS)),$(if $(wildcard .task.mk),,.task.mk : ; curl - fsSL https :// raw . githubusercontent . com / daylinmorgan / task . mk / v 22.9.19/ 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. -include .task.mk $(if $(wildcard .task.mk),,.task.mk : ; curl - fsSL https :// raw . githubusercontent . com / daylinmorgan / task . mk / v 22.9.19/ task . mk - o . task . mk ) Alternatively, you can use the builtin rule _update-task.mk to update to the latest development version. See Usage to get started running all your tasks. See Examples for more use cases.","title":"Setup"},{"location":"#zsh-completions-for-gnu-make","text":"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. zstyle ':completion::complete:make:*:targets' call-command true","title":"Zsh Completions for GNU Make"},{"location":"#why-make","text":"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 , 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 . 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.","title":"Why Make?"},{"location":"#simpler-alternative","text":"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 ). ## 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];}' $<","title":"Simpler Alternative"},{"location":"usage/","text":"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 . 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. You can place these anywhere, but I recommend adding these notes directly above their relevant recipes. The format is ## | ## build | build the project .PHONY : build build : ... Now when you invoke make help it will parse these and generate your help output. In addition to a generic help output you can expose some configuration settings with make vars . 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.) To use tprint you call it with the builtin make call function. It accepts only one argument: an unquoted f-string literal. All strings passed to tprint have access to an object ansi or a for simplicity. This stores ANSI escape codes which can be used to style your text. ## build | compile the source .PHONY : build build : $( 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 . Or a tuple/list to define an RBG 24-bit color, for instance a.custom(fg=(5,10,255)) . 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 . # ---- [config] ---- # HEADER_STYLE ?= b_cyan ACCENT_STYLE ?= b_yellow PARAMS_STYLE ?= $( ACCENT_STYLE ) GOAL_STYLE ?= $( ACCENT_STYLE ) MSG_STYLE ?= faint DIVIDER_STYLE ?= default DIVIDER ?= \u2500 HELP_SEP ?= \u2502 # python f-string literals EPILOG ?= USAGE ?={ ansi. $( HEADER_STYLE ) } usage { ansi.end } : \\n make \\n INHERIT_SHELL ?= To use a custom color for one of the predefined configuration variables specify only the custom method. 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 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 may be easier than balancing sub-shells and strung together awk commands. When make expands the function it will take the parameters passed to py and expand them. $(1) is the variable name and $(2) in this case is the implicit pattern from the rule. Pay attention to quotes. If you need to debug your python script, use DEBUG=1 when you run make and it will first print the script that will be piped to python . 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 list-% : $( call py,list_files_py, $* ) For what it's worth there is also a predefined function for bash (named tbash ) as well should you need to accomplish something similar of more easily embedding your bash script rather than having to escape every line with a backslash. define bash_script figlet task.mk 2>/dev/null || echo 'no figlet : (' echo \"This is from bash\" cat /etc/hostname printf \"%s\\n\" \"$(2)\" endef .PHONY : test - bash test-bash : $( call tbash,bash_script,test bash multiline )","title":"Usage"},{"location":"usage/#usage","text":"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 . 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. You can place these anywhere, but I recommend adding these notes directly above their relevant recipes. The format is ## | ## build | build the project .PHONY : build build : ... Now when you invoke make help it will parse these and generate your help output. In addition to a generic help output you can expose some configuration settings with make vars . 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.) To use tprint you call it with the builtin make call function. It accepts only one argument: an unquoted f-string literal. All strings passed to tprint have access to an object ansi or a for simplicity. This stores ANSI escape codes which can be used to style your text. ## build | compile the source .PHONY : build build : $( 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 . Or a tuple/list to define an RBG 24-bit color, for instance a.custom(fg=(5,10,255)) . See this project's make info for an example.","title":"Usage"},{"location":"usage/#configuration","text":"You can quickly customize some of the default behavior of task.mk by overriding the below variables prior to the -include .task.mk . # ---- [config] ---- # HEADER_STYLE ?= b_cyan ACCENT_STYLE ?= b_yellow PARAMS_STYLE ?= $( ACCENT_STYLE ) GOAL_STYLE ?= $( ACCENT_STYLE ) MSG_STYLE ?= faint DIVIDER_STYLE ?= default DIVIDER ?= \u2500 HELP_SEP ?= \u2502 # python f-string literals EPILOG ?= USAGE ?={ ansi. $( HEADER_STYLE ) } usage { ansi.end } : \\n make \\n INHERIT_SHELL ?= To use a custom color for one of the predefined configuration variables specify only the custom method. HEADER_STYLE = custom ( fg = 171 ,bg = 227 ) NOTE : HELP_SEP does not change the argument definitions syntax only the format of make help .","title":"Configuration"},{"location":"usage/#advanced-usage-embedded-python-scripts","text":"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 may be easier than balancing sub-shells and strung together awk commands. When make expands the function it will take the parameters passed to py and expand them. $(1) is the variable name and $(2) in this case is the implicit pattern from the rule. Pay attention to quotes. If you need to debug your python script, use DEBUG=1 when you run make and it will first print the script that will be piped to python . 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 list-% : $( call py,list_files_py, $* ) For what it's worth there is also a predefined function for bash (named tbash ) as well should you need to accomplish something similar of more easily embedding your bash script rather than having to escape every line with a backslash. define bash_script figlet task.mk 2>/dev/null || echo 'no figlet : (' echo \"This is from bash\" cat /etc/hostname printf \"%s\\n\" \"$(2)\" endef .PHONY : test - bash test-bash : $( call tbash,bash_script,test bash multiline )","title":"Advanced Usage: Embedded Python Scripts"},{"location":"examples/","text":"Examples Confirm Perform a basic confirmation test with the user and exit with error code 1 if input is N/n. Embedded Scripts Use the builtin functions to write multi-line python/bash scripts directly in your Makefile Recipe Help Display the target, docstring and recipe for a given target then exit.","title":"Examples"},{"location":"examples/#examples","text":"Confirm Perform a basic confirmation test with the user and exit with error code 1 if input is N/n. Embedded Scripts Use the builtin functions to write multi-line python/bash scripts directly in your Makefile Recipe Help Display the target, docstring and recipe for a given target then exit.","title":"Examples"},{"location":"examples/check/","text":"Check check.mk ## 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 interactivity w/ task.mk \\n endef .DEFAULT_GOAL = help include $(shell git rev-parse --show-toplevel)/task.mk","title":"Check"},{"location":"examples/check/#check","text":"check.mk ## 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 interactivity w/ task.mk \\n endef .DEFAULT_GOAL = help include $(shell git rev-parse --show-toplevel)/task.mk","title":"Check"},{"location":"examples/embedded/","text":"Embedded embedded.mk ### 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 examples of embedded scripts in ` { a.magenta } Makefile { a.end } ` endef .DEFAULT_GOAL = help include $(shell git rev-parse --show-toplevel)/task.mk","title":"Embedded"},{"location":"examples/embedded/#embedded","text":"embedded.mk ### 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 examples of embedded scripts in ` { a.magenta } Makefile { a.end } ` endef .DEFAULT_GOAL = help include $(shell git rev-parse --show-toplevel)/task.mk","title":"Embedded"},{"location":"examples/recipe-help/","text":"Recipe Help recipe-help.mk ## deps-only | a task/target with dependencies .PHONY : deps - only deps-only : foo ## foo | a dummy rule that depends on the local files .PHONY : foo foo : $( wildcard * ) @echo 'this is a dummy rule' # bar but no docstring .PHONY : bar bar : @echo 'some rule with no help string' define USAGE {a.header}usage : { a . end } make make help endef .DEFAULT_GOAL = help include $(shell git rev-parse --show-toplevel)/task.mk","title":"Recipe Help"},{"location":"examples/recipe-help/#recipe-help","text":"recipe-help.mk ## deps-only | a task/target with dependencies .PHONY : deps - only deps-only : foo ## foo | a dummy rule that depends on the local files .PHONY : foo foo : $( wildcard * ) @echo 'this is a dummy rule' # bar but no docstring .PHONY : bar bar : @echo 'some rule with no help string' define USAGE {a.header}usage : { a . end } make make help endef .DEFAULT_GOAL = help include $(shell git rev-parse --show-toplevel)/task.mk","title":"Recipe Help"}]} \ No newline at end of file diff --git a/sitemap.xml b/sitemap.xml index cca0768..e98f21f 100644 --- a/sitemap.xml +++ b/sitemap.xml @@ -2,27 +2,32 @@ https://gh.dayl.in/task.mk/ - 2022-09-22 + 2022-09-24 daily https://gh.dayl.in/task.mk/usage/ - 2022-09-22 + 2022-09-24 daily https://gh.dayl.in/task.mk/examples/ - 2022-09-22 + 2022-09-24 daily https://gh.dayl.in/task.mk/examples/check/ - 2022-09-22 + 2022-09-24 daily https://gh.dayl.in/task.mk/examples/embedded/ - 2022-09-22 + 2022-09-24 + daily + + + https://gh.dayl.in/task.mk/examples/recipe-help/ + 2022-09-24 daily \ No newline at end of file diff --git a/sitemap.xml.gz b/sitemap.xml.gz index f88099c678c45916de740d2de0c77595781244ea..7525b822885f8417bfcb772391b331cd0b6ccb3f 100644 GIT binary patch literal 250 zcmV*?z)27bH--&`Q0o8mzBv?C2fHE9>kKt4|I?JGHo z9Y1G}P?`!y9EdF?y)ib=GeuV*$b@vthM}_cf$SNwjvk2EHFcJP$L&7cPf9E;SZj=> zTHZW$krjy}4I|@h0oJ_45+*JBuJ7CK(DpACd1fn2Ss4v{W%w3aI)CGAl{`e)ugM>s z&L|CR(hROLBoDZ4xw;!_+_oZwPtY3lwkUjKdy(=$?c1isPeXpN}dhy>FLv34Dxh|q4~y{d`>-k;vH)+nQVP>J$rw9ZJ*gm z9prfqgr%u)qMi+otq>J?WE;#3IywBD@k?3l!&Sm2xr@NB$se80 qq#f?k3@ + + + + + + + + + + + + + + + +
    + Recipe help + +
    + + + + + + +