mirror of
https://github.com/daylinmorgan/task.mk.git
synced 2024-11-14 21:17:53 -06:00
1 line
No EOL
12 KiB
JSON
1 line
No EOL
12 KiB
JSON
{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":"task.mk <p> the task runner for GNU Make you've been missing </p> <p> Documentation </p> <p></p> <p>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.</p> <p><code>Task.mk</code>, is a standalone <code>Makefile</code> you can deploy alongside your own to add some QOL improvements for your users and fellow maintainers.</p> <p>Current Features:</p> <ul> <li>ANSI escape code support (including NO_COLOR) </li> <li>formatted help output</li> <li>custom print function</li> <li>confirmation prompt</li> <li>goal phonifier (disabled by default)</li> </ul> <p>Depends on <code>GNU Make</code>, obviously and <code>Python >=3.7</code>, and <code>bash</code> (or <code>zsh</code>).</p> <p>Wait python?!?!, I'm not <code>pip</code> installing some package just to parse my makefile. I agree, all you need is one file <code>.task.mk</code> You can automagically include it with just two additional lines to your <code>Makefile</code> (and probably one to your <code>.gitignore</code>) and you're good to go.</p>"},{"location":"#setup","title":"Setup","text":"<p>One line setup to download .task.mk and add appropriate includes to your <code>Makefile</code>. <pre><code>bash <(curl -fsSL gh.dayl.in/task.mk/init) # or w/ TASKMK_VERSION=\n</code></pre></p> <p>You can include this as an optional dependency on your project by adding the below lines to the end of your <code>Makefile</code>. If someone tries to invoke <code>make help</code> it will download <code>.task.mk</code> for them.</p> <pre><code>-include .task.mk\n$(if $(filter help,$(MAKECMDGOALS)),$(if $(wildcard .task.mk),,.task.mk: ; curl -fsSL https://raw.githubusercontent.com/daylinmorgan/task.mk/v23.1.2/task.mk -o .task.mk))\n</code></pre> <p>If you plan to use any features besides the help prompt you may want to instead commit <code>.task.mk</code> to version control or drop the <code>$(MAKECMDGOALS)</code> check so it's always downloaded once <code>make</code> is invoked.</p> <pre><code>-include .task.mk\n$(if $(wildcard .task.mk),,.task.mk: ; curl -fsSL https://raw.githubusercontent.com/daylinmorgan/task.mk/v23.1.2/task.mk -o .task.mk)\n</code></pre> <p>For more info see the documentation.</p>"},{"location":"usage/","title":"Usage","text":"<p><code>Task.mk</code> can be included in any standard <code>GNUMakefile</code>. If it's been properly sourced you will have access to the below features/recipes.</p> <p>See examples for more info.</p>"},{"location":"usage/#builtin-recipes","title":"Builtin Recipes","text":""},{"location":"usage/#help","title":"Help","text":"<p>Invoked with either <code>make help</code> or <code>make h</code>.</p> <p>Adding goals to the builtin help recipe just requires documenting your <code>Makefile</code> with comments. The format is <code>## <recipe> |> <msg></code> or <code><recipe>: ## <msg></code></p> <pre><code>## build |> build the project\nbuild:\n...\n\nbuild: ## build the project\n</code></pre> <p>Now when you invoke <code>make help</code> it will parse these and generate your help output. In addition you can add raw text to the help output using the format <code>### <rawmsg></code>.</p> <p>Both recipe documentation and raw messages can be modified with additional arguments delimited by <code>|></code>.</p> <p>For example:</p> <pre><code>### build related recipes |> --align center --divider\nbuild: ## build the project |> --msg-style bold\n...\npackage: ## package the project |> -gs b_cyan\n</code></pre> <p><code>Task.mk</code> 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: <code>make help build</code>.</p> <p>All recipes prefixed with and underscore will be hidden even if documented. However, they can be viewed by invoking <code>make _help</code>.</p>"},{"location":"usage/#vars","title":"Vars","text":"<p>In addition to a generic help output you can expose some configuration settings with <code>make vars</code> or <code>make v</code>. To do so define the variables you'd like to print with <code>PRINT_VARS := VAR1 VAR2 VAR3</code>.</p>"},{"location":"usage/#builtin-functions","title":"Builtin Functions","text":""},{"location":"usage/#phonify","title":"Phonify","text":"<p>Phonify is a new experimental feature of <code>task.mk</code> that solves one of the biggest gotchas of using <code>make</code> as a task runner! It stands to reason the tasks you document are likely to all be phony recipes Rather than write <code>.PHONY: <goal></code> repeatedly, simply enable <code>task.mk</code>'s phonifier.</p> <p><code>Task.mk</code> will then parse your <code>Makefile</code> for documented tasks and generate the necessary <code>.PHONY: <recipes></code> line to ensure they are always executed. To use this feature set the <code>PHONIFY</code> environment variable before including <code>.task.mk</code>. To avoid adding a documented task/recipe to <code>.PHONY</code>, use <code>|> --not-phony</code> after the recipe message.</p>"},{"location":"usage/#tprint","title":"Tprint","text":"<p>Besides the <code>help</code> and <code>vars</code> 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 <code>tprint</code> or <code>tprint-verbose</code> (<code>tprint-verbose</code> is for use within a multiline sub-shell that has already been silenced, see the version-check rule of this project's <code>Makefile</code> for an example).</p> <p>To use <code>tprint</code> you call it with the builtin <code>make</code> call function. It accepts only one argument: an unquoted f-string literal. All strings passed to <code>tprint</code> have access to an object <code>ansi</code> or <code>a</code> for simplicity. This stores ANSI escape codes which can be used to style your text.</p> <pre><code>.PHONY: build\nbuild: ## compile the source\n$(call tprint,{a.cyan}Build Starting{a.end})\n...\n $(call tprint,{a.green}Build Finished{a.end})\n</code></pre> <p>See this projects <code>make info</code> for more examples of <code>tprint</code>.</p> <p>To see the available colors and formatting(bold,italic,etc.) use the hidden recipe <code>make _print-ansi</code>.</p> <p>In addition, you can use custom colors using the builtin <code>ansi.custom</code> or (<code>a.custom</code>) method. It has two optional arguments <code>fg</code> and <code>bg</code>. 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 <code>a.custom(fg=(5,10,255))</code>. See this project's <code>make info</code> for an example.</p>"},{"location":"usage/#configuration","title":"Configuration","text":"<p>You can quickly customize some of the default behavior of <code>task.mk</code> by overriding the below variables prior to the <code>-include .task.mk</code>. These can also for instance included in a seperate file <code>.task.cfg.mk</code>.</p> <pre><code># ---- [config] ---- #\nHEADER_STYLE ?= b_cyan\nACCENT_STYLE ?= b_yellow\nPARAMS_STYLE ?= $(ACCENT_STYLE)\nGOAL_STYLE ?= $(ACCENT_STYLE)\nMSG_STYLE ?= faint\nDIVIDER_STYLE ?= default\nDIVIDER ?= \u2500\nHELP_SEP ?= \u2502\n# python f-string literals\nEPILOG ?=\nUSAGE ?={ansi.$(HEADER_STYLE)}usage{ansi.end}:\\n make <recipe>\\n\nTASKMK_SHELL ?=\nPHONIFY ?=\n</code></pre> <p>To use a custom color for one of the predefined configuration variables specify only the custom method.</p> <pre><code>HEADER_STYLE = custom(fg=171,bg=227)\n</code></pre> <p>NOTE: <code>HELP_SEP</code> does not change the argument definitions syntax only the format of <code>make help</code>.</p>"},{"location":"usage/#advanced-usage-embedded-scripts","title":"Advanced Usage: Embedded Scripts","text":"<p>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 <code>Makefile</code> may be easier than balancing sub-shells and strung together awk commands.</p> <p>When <code>make</code> expands the function it will take the parameters passed to <code>py</code> and expand them. <code>$(1)</code> is the variable name and <code>$(2)</code> in this case is the implicit pattern from the rule. Pay attention to quotes. If you need to debug your python script, use <code>TASKMK_DEBUG=1</code> when you run <code>make</code> and it will first print the script that will be piped to <code>python</code>.</p> <pre><code>define list_files_py\nfrom pathlib import Path\nprint(\"files in $(2)\")\nprint([f.name for f in (Path(\"$(2)\").iterdir())])\nendef\n## list-% | use pathlib.Path to list files\nlist-%:\n$(call py,list_files_py,$*)\n</code></pre> <p>For what it's worth there is also a predefined function for <code>bash</code> (named <code>tbash</code>) 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.</p> <pre><code>define bash_script\nfiglet task.mk 2>/dev/null || echo 'no figlet :('\necho \"This is from bash\"\ncat /etc/hostname\nprintf \"%s\\n\" \"$(2)\"\nendef\n.PHONY: test-bash\ntest-bash:\n$(call tbash,bash_script,test bash multiline)\n</code></pre>"},{"location":"examples/","title":"Examples","text":"Confirm <p>Perform a basic confirmation test with the user and exit with error code 1 if input is N/n.</p> Embedded Scripts <p>Use the builtin functions to write multi-line python/bash scripts directly in your <code>Makefile</code></p> Recipe Help <p>Display the target, docstring and recipe for a given target then exit.</p> Phonify <p>Automatically generate the phony call for any documented tasks.</p>"},{"location":"examples/check/","title":"Check","text":"Makefile (check)<pre><code>.PHONY: check\ncheck: ## get user confirmation or exit\n$(call tconfirm,Would you like to proceed?)\n@echo \"you said yes!\"\ndefine USAGE\n{a.$(HEADER_STYLE)}usage:{a.end}\\n make <recipe>\\n\\n interactivity w/ task.mk\\n\nendef\n.DEFAULT_GOAL = help\ninclude .task.mk\n</code></pre>"},{"location":"examples/embedded/","title":"Embedded","text":"Makefile (embedded)<pre><code>### examples of task.mk features |> --divider --align center --msg-style b_red\ndefine list_files_py\nfrom pathlib import Path\nprint(\"files in $(2)\")\nprint([f.name for f in (Path(\"$(2)\").iterdir())])\nendef\n## list-% |> use pathlib.Path to list files\n### name the directory in rule (make list-src) |> --align sep\nlist-%:\n$(call py,list_files_py,$*)\n# dollar signs will always be a problem :|\ndefine bash_script\necho \"Is the process running bash? We can check with ps\"\nps -o args= -p $$$$ | grep -E -m 1 -o '\\w{0,5}sh'\necho \"Get input at runtime\"\nprintf \"type input now! \"\nread -r name\necho \"you typed -> $$name\"\necho \"the argument below as given in the makefile itself\"\necho \"it's expanded before the script is passed to bash\"\nprintf \"%s\\n\" \"$(2)\"\nendef\n.PHONY: embedded-bash\nembedded-bash: ## bash script with pipes and make input\n$(call tbash,bash_script,bash multiline is working \ud83e\udd1e)\ndefine USAGE\n{a.$(HEADER_STYLE)}usage:{a.end}\\n make <recipe>\\n\\n examples of embedded scripts in `{a.magenta}Makefile{a.end}`\\n\nendef\n.DEFAULT_GOAL = help\ninclude .task.mk\n</code></pre>"},{"location":"examples/phonify/","title":"Phonify","text":"Makefile (phonify)<pre><code>a-task: ## will be marked phony\n@echo a-task executed\n\nb-task: ## wont be marked phony |> --not-phony\n@echo b-task executed\n\nc-task:\n@echo c-task executed\n\n.PHONY: gen-task-files\ngen-task-files:\ntouch a-task b-task c-task\n\ndefine USAGE\n{a.$(HEADER_STYLE)}usage:{a.end}\\n make <recipe>\\n\nphonifying tasks\n {a.faint}hint: there is also a c-task...{a.end}\\n\nendef\nPHONIFY = true\n.DEFAULT_GOAL = help\ninclude .task.mk\n</code></pre>"},{"location":"examples/recipe-help/","title":"Recipe Help","text":"Makefile (recipe-help)<pre><code>.PHONY: deps-only\ndeps-only: foo ## a task/target with dependencies\n.PHONY: foo\nfoo: $(wildcard *) ## a dummy rule that depends on the local files\n@echo 'this is a dummy rule'\n# bar but no docstring\n.PHONY: bar\nbar:\n@echo 'some rule with no help string'\ndefine USAGE\n{a.header}usage:{a.end}\n make <recipe>\n make help <recipe>\n\nendef\n.DEFAULT_GOAL = help\ninclude .task.mk\n</code></pre>"}]} |