diff --git a/.gitignore b/.gitignore index 0b71aad..33ff9cf 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,6 @@ soft/ tmp/ + +book/ +build/ diff --git a/Makesurefile b/Makesurefile index 92c6d16..960c2ed 100644 --- a/Makesurefile +++ b/Makesurefile @@ -2,45 +2,53 @@ @options timing @define NEXT_VERSION '0.9.23' -@define GOAWK_VERSION '1.25.0' -@define JUST_VERSION '1.3.0' -@define FHTAGN_VERSION 'v0.1.1' +@define GOAWK_VERSION '1.25.0' # https://github.com/benhoyt/goawk/releases +@define JUST_VERSION '1.3.0' # https://github.com/casey/just/releases +@define FHTAGN_VERSION 'v0.1.1' # https://github.com/xonixx/fhtagn/releases +@define MDBOOK_VERSION 'v0.4.37' # https://github.com/rust-lang/mdBook/releases +@define MDBOOK_LINKCHECK_VERSION 'v0.7.7' # https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases +@define MDBOOKER_VERSION '11572b1' # https://github.com/xonixx/mdbooker/releases + @define GOAWK "goawk$GOAWK_VERSION" @define JUST "just$JUST_VERSION" -@define FHTAGN_URL "https://github.com/xonixx/fhtagn/raw/$FHTAGN_VERSION/fhtagn.awk" @define REPO 'xonixx/makesure' @define AWK "${AWK:-awk}" +@lib dl + download() { + local url="$1" + local file="$2" + + if command -v wget >/dev/null + then + wget "$url" -O"$file" + elif command -v curl >/dev/null + then + curl -L "$url" -o "$file" + else + false + fi + } + @goal soft_folder_created @private @reached_if [[ -d "soft" ]] mkdir soft +@define FHTAGN_URL "https://github.com/xonixx/fhtagn/raw/$FHTAGN_VERSION/fhtagn.awk" @define FHTAGN "./soft/fhtagn$FHTAGN_VERSION.awk" @goal fhtagn_installed @private @depends_on soft_folder_created @reached_if [[ -x "$FHTAGN" ]] - if command -v wget >/dev/null - then - wget "$FHTAGN_URL" -O"$FHTAGN" - elif command -v curl >/dev/null - then - curl -L "$FHTAGN_URL" -o "$FHTAGN" - else - echo "can't dl fhtagn" - exit 2 - fi +@use_lib dl + download "$FHTAGN_URL" "$FHTAGN" chmod +x "$FHTAGN" -@goal cleaned @private - -@goal cleaned_soft @private +@goal cleaned_soft +@doc 'rm soft folder' @reached_if [[ ! -d "soft" ]] rm -r "soft" -@goal cleaned_all @private -@depends_on cleaned cleaned_soft - @lib awk_ver awk_ver() { local key="$1" @@ -237,13 +245,14 @@ @goal installed_bwk @private @reached_if [[ -f soft/bwk ]] @depends_on soft_folder_created +@use_lib dl echo echo "Fetching BWK..." echo cd "soft" - wget https://github.com/onetrueawk/awk/archive/refs/heads/master.tar.gz -Obwk.tar.gz + download https://github.com/onetrueawk/awk/archive/refs/heads/master.tar.gz bwk.tar.gz tar xzvf bwk.tar.gz rm bwk.tar.gz @@ -296,6 +305,7 @@ @goal installed_gawk @params VERSION EXE_NAME @private @reached_if [[ -f soft/"$EXE_NAME" ]] @depends_on soft_folder_created +@use_lib dl echo echo "Fetching Gawk-$VERSION..." echo @@ -315,7 +325,7 @@ # dlFolder="gawk-$VERSION" # tarOpts="xvf" # fi - wget "$dlUrl" + download "$dlUrl" "$G" tar "${tarOpts:-xzvf}" "$G" rm "$G" @@ -358,13 +368,15 @@ @goal installed_busybox @private @reached_if [[ -x ./soft/busybox ]] - wget 'https://busybox.net/downloads/binaries/1.31.0-i686-uclibc/busybox' -O ./soft/busybox +@use_lib dl + download 'https://busybox.net/downloads/binaries/1.31.0-i686-uclibc/busybox' ./soft/busybox chmod +x ./soft/busybox echo "Installed: $(./soft/busybox | head -n 1)" @goal installed_goawk @private @reached_if [[ -f soft/$GOAWK ]] @depends_on soft_folder_created +@use_lib dl echo echo "Fetching GoAWK $GOAWK_VERSION ..." echo @@ -381,7 +393,7 @@ fi F=goawk_v${GOAWK_VERSION}_${os}_amd64.tar.gz - wget "https://github.com/benhoyt/goawk/releases/download/v$GOAWK_VERSION/$F" + download "https://github.com/benhoyt/goawk/releases/download/v$GOAWK_VERSION/$F" "$F" tar xzvf "$F" goawk rm "$F" @@ -418,6 +430,7 @@ @goal installed_just @private @reached_if [[ -f "soft/$JUST" ]] @depends_on soft_folder_created +@use_lib dl echo echo "Fetching Just $JUST_VERSION ..." echo @@ -425,7 +438,7 @@ cd "soft" F=just-$JUST_VERSION-x86_64-unknown-linux-musl.tar.gz - wget "https://github.com/casey/just/releases/download/$JUST_VERSION/$F" + download "https://github.com/casey/just/releases/download/$JUST_VERSION/$F" "$F" tar xzvf "$F" just mv just "$JUST" rm "$F" @@ -494,3 +507,59 @@ do print gensub(/#([0-9]+)/,"[\\0](https://github.com/xonixx/makesure/issues/\\1)", "g") }' done + +# === Documentation site === +@goal deploy_site + HOST='xonix@server.maximullaris.com' + DEST="$HOST":/var/www/makesure + + rsync -aP build/ "$DEST/" + +@goal site_compile +@depends_on site_soft_installed + rm -rf book; mkdir book; awk -f "$MDBOOKER" README.md + "$MDBOOK" build + "$MDBOOK_LINKCHECK" -s # check broken links + +@goal site_soft_installed @private +@depends_on mdbook_installed +@depends_on mdbook-linkcheck_installed +@depends_on mdbooker_installed + +@define MDBOOKER "./soft/mdbooker_$MDBOOKER_VERSION.awk" +@define MDBOOK "./soft/mdbook_$MDBOOK_VERSION" +@define MDBOOK_LINKCHECK "./soft/mdbook-linkcheck_$MDBOOK_LINKCHECK_VERSION" + +@define MDBOOKER_URL "https://github.com/xonixx/mdbooker/raw/$MDBOOKER_VERSION/mdbooker.awk" + +@goal mdbooker_installed @private +@depends_on soft_folder_created +@reached_if [[ -x "$MDBOOKER" ]] +@use_lib dl + download "$MDBOOKER_URL" "$MDBOOKER" + chmod +x "$MDBOOKER" + +@goal mdbook_installed @private +@reached_if [[ -x "$MDBOOK" ]] +@use_lib dl + F="mdbook-$MDBOOK_VERSION-x86_64-unknown-linux-musl.tar.gz" + URL="https://github.com/rust-lang/mdBook/releases/download/$MDBOOK_VERSION/$F" + ( cd /tmp + download "$URL" "$F" + tar -xzvf "$F" mdbook ) + mv /tmp/mdbook "$MDBOOK" + "$MDBOOK" --version + rm "/tmp/$F" + +@goal mdbook-linkcheck_installed @private +@reached_if [[ -x "$MDBOOK_LINKCHECK" ]] +@use_lib dl + F="mdbook-linkcheck.x86_64-unknown-linux-gnu.zip" + URL="https://github.com/Michael-F-Bryan/mdbook-linkcheck/releases/download/$MDBOOK_LINKCHECK_VERSION/$F" + ( cd /tmp + download "$URL" "$F" + unzip -p "$F" mdbook-linkcheck >mdbook-linkcheck ) + mv /tmp/mdbook-linkcheck "$MDBOOK_LINKCHECK" + chmod +x "$MDBOOK_LINKCHECK" + "$MDBOOK_LINKCHECK" --version + rm "/tmp/$F" \ No newline at end of file diff --git a/README.md b/README.md index 9ec442b..c9dced3 100644 --- a/README.md +++ b/README.md @@ -221,7 +221,7 @@ Example: ### @goal -Syntax #1: +#### Simple goal ``` @goal goal_name [ @private ] ``` @@ -254,7 +254,7 @@ Invoking `./makesure` without arguments will attempt to call the goal named `def echo "I'm default goal" ``` -Syntax #2: +#### Glob goal ``` @goal [ goal_name ] @glob [ @private ] ``` @@ -320,16 +320,16 @@ to be able to run each test individually (`./makesure test2.js` for example) and In case if you need to glob the files with spaces in their names, please check the [naming rules section](#naming-rules) below. -### Parameterized goals +#### Parameterized goal Make code easier to reuse. Declaration syntax (using `@params`): -```shell +```sh @goal goal_name @params A B C ``` Usage syntax (using `@args`): -```shell +```sh @goal other_goal @params PARAM @depends_on goal_name @args 'value1' 'value 2' PARAM ``` @@ -338,7 +338,7 @@ The idea of using two complementary keywords `@params` + `@args` was inspired by Example: -```shell +```sh @goal file_downloaded @params FILE_NAME echo "Downloading $FILE_NAME..." @@ -397,7 +397,7 @@ Note, the goal's body parameter values will appear as environment variables (as Note, you can reference the `@define`-ed variables in the arguments of the parameterized goals: -```shell +```sh @define HELLO 'hello' @goal parameterized_goal @params ARG @@ -425,6 +425,45 @@ Please find a more real-world example [here](https://github.com/xonixx/fhtagn/bl For more technical consideration regarding this feature see [parameterized_goals.md](docs/parameterized_goals.md). +#### Naming rules + +It's *recommended* that you name your goals using alphanumeric chars + underscore. + +However, it's possible to name a goal any way you want provided that you apply proper escaping: + +```sh +@goal 'name with spaces' # all chars between '' have literal meaning, same as in shell, ' itself is not allowed in it + +@goal $'name that contains \' single quote' # if you need to have ' in a string, use dollar-strings and escape it + +@goal usual_name +``` + +Now `./makesure -l` gives: +``` +Available goals: + 'name with spaces' + $'name that contains \' single quote' + usual_name +``` + +Note, how goal names are already escaped in output. This is to make it easier for you to call it directly: +```sh +./makesure $'name that contains \' single quote' +``` + +Same naming rules apply to other directives (like `@doc`). + +Usually you won't need this escaping tricks often, but they can be especially in use for `@glob` goals if the relevant files have spaces in them: + +```sh +@goal @glob 'file\ with\ spaces*.txt' +@goal other + @depends_on 'file with spaces1.txt' +``` + +More info on this topic is covered in the [issue](https://github.com/xonixx/makesure/issues/63). + ### @doc Only valid: inside `@goal`. @@ -614,49 +653,10 @@ Only valid: inside `@goal`. Only single `@use_lib` per goal is allowed. -### Naming rules - -It's *recommended* that you name your goals using alphanumeric chars + underscore. - -However, it's possible to name a goal any way you want provided that you apply proper escaping: - -```sh -@goal 'name with spaces' # all chars between '' have literal meaning, same as in shell, ' itself is not allowed in it - -@goal $'name that contains \' single quote' # if you need to have ' in a string, use dollar-strings and escape it - -@goal usual_name -``` - -Now `./makesure -l` gives: -``` -Available goals: - 'name with spaces' - $'name that contains \' single quote' - usual_name -``` - -Note, how goal names are already escaped in output. This is to make it easier for you to call it directly: -```sh -./makesure $'name that contains \' single quote' -``` - -Same naming rules apply to other directives (like `@doc`). - -Usually you won't need this escaping tricks often, but they can be especially in use for `@glob` goals if the relevant files have spaces in them: - -```sh -@goal @glob 'file\ with\ spaces*.txt' -@goal other - @depends_on 'file with spaces1.txt' -``` - -More info on this topic is covered in the [issue](https://github.com/xonixx/makesure/issues/63). - ## Bash completion Install Bash completion for `./makesure` locally -```shell +```sh [[ ! -f ~/.bash_completion ]] && touch ~/.bash_completion grep makesure ~/.bash_completion >/dev/null || echo '. ~/.makesure_completion.bash' >> ~/.bash_completion curl "https://raw.githubusercontent.com/xonixx/makesure/main/completion.bash?token=$(date +%s)" -o ~/.makesure_completion.bash @@ -694,7 +694,7 @@ echo 'Please reopen the shell to activate completion.' Find some contributor instructions in [DEVELOPER.md](docs/DEVELOPER.md). -#### AWK +### AWK The core of this tool is implemented in [AWK](https://en.wikipedia.org/wiki/AWK). Almost all major implementations of AWK will work. Tested and officially supported are [Gawk](https://www.gnu.org/software/gawk/), [BWK](https://github.com/onetrueawk/awk), [mawk](https://invisible-island.net/mawk/). This means that the default AWK implementation in your OS will work. @@ -711,19 +711,19 @@ Developed in [xonixx/intellij-awk](https://github.com/xonixx/intellij-awk). ## Similar tools -- **just** https://github.com/casey/just `Rust` +- **just** [https://github.com/casey/just](https://github.com/casey/just) `Rust` - just is a handy way to save and run project-specific commands -- **Taskfile** https://github.com/adriancooney/Taskfile `Bash` +- **Taskfile** [https://github.com/adriancooney/Taskfile](https://github.com/adriancooney/Taskfile) `Bash` - A Taskfile is a bash \[...] script that follows a specific format \[...], sits in the root of your project \[...] and contains the tasks to build your project. -- **Task** https://github.com/go-task/task `Go` +- **Task** [https://github.com/go-task/task](https://github.com/go-task/task) `Go` - Task is a task runner / build tool that aims to be simpler and easier to use than, for example, GNU Make. -- **mmake** https://github.com/tj/mmake `Go` +- **mmake** [https://github.com/tj/mmake](https://github.com/tj/mmake) `Go` - Modern Make is a small program which wraps `make` to provide additional functionality -- **Robo** https://github.com/tj/robo `Go` +- **Robo** [https://github.com/tj/robo](https://github.com/tj/robo) `Go` - Simple Go / YAML-based task runner for the team -- **haku** https://github.com/VladimirMarkelov/haku `Rust` +- **haku** [https://github.com/VladimirMarkelov/haku](https://github.com/VladimirMarkelov/haku) `Rust` - A task/command runner inspired by 'make' -- **Invoke-Build** https://github.com/nightroman/Invoke-Build `PowerShell` +- **Invoke-Build** [https://github.com/nightroman/Invoke-Build](https://github.com/nightroman/Invoke-Build) `PowerShell` - Build Automation in PowerShell -- **make** https://www.gnu.org/software/make/ `C` +- **make** [https://www.gnu.org/software/make/](https://www.gnu.org/software/make/) `C` - \[...] a tool which controls the generation of executables and other non-source files of a program from the program's source files. diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..3eafcda --- /dev/null +++ b/book.toml @@ -0,0 +1,13 @@ +[book] +language = "en" +src = "book" +title = "Makesure Manual" + +[build] +build-dir = "build" + +[output.html] +git-repository-url = "https://github.com/xonixx/makesure" +#site-url = "/" + +#[output.linkcheck] \ No newline at end of file