7.1 KiB
Contents
- What is a cli?
- How do I add a command-line flag?
- How do I access the value of a command-line argument?
- How do I incorporate BASH3 Boilerplate into my own project?
- What is a magic variable?
- How do I incorporate BASH3 Boilerplate into my own project?
- How can I contribute to this project?
Frequently Asked Questions
What is a cli?
A 'cli' is a command-line interface.
How do I incorporate BASH3 Boilerplate into my own project?
After installing b3bp, you can incorporate it into your project in one of two ways:
- Copy the desired portions of main.sh into your own script.
- Use main.sh as a template and start pressing the delete-key for unwanted things
Once the main.sh has been tailor-made for your project, you can either append your own script in the same file, or source it in the following ways:
- Copy main.sh into the same directory as your script and then edit and embed it into your script using Bash's
sourceinclude feature, e.g.
#!/usr/bin/env bash
source main.sh
- Source main.sh in your script or at the command line
#!/usr/bin/env bash
source main.sh
How do I add a command-line flag?
- Copy the line from the main.sh read block that most resembles the desired behavior and paste the line into the same block.
- Edit the single-character (e.g.,
-d) and, if present, the multi-character (e.g.,--debug) versions of the flag in the copied line. - Omit the
[arg]text in the copied line, if the desired flag takes no arguments. - Omit or edit the text after
Default:to set or not set default values, respectively. - Omit the
Required.text, if the flag is optional.
How do I access the value of a command-line argument?
To find out the value of an argument, append the corresponding single-character flag to $arg_. For example, if the [read block] contains the line
-t --temp [arg] Location of tempfile. Default="/tmp/bar"
then you can evaluate the corresponding argument and assign it to a variable as follows:
__temp_filename="${arg_t}"
What is a magic variable?
The magic variables in main.sh are special in that they have a different value, depending on your environment. You can use ${__file} to get a reference to your current script, and ${__dir} to get a reference to the directory it lives in. This is not to be confused with the location of the calling script that might be sourcing the ${__file}, which is accessible via ${0}, or the current directory of the administrator running the script, accessible via $(pwd).
How do I submit an issue report?
Please visit our Issues page.
How can I contribute to this project?
Please fork this repository. After that, create a branch containing your suggested changes and submit a pull request based on the master branch of https://github.com/kvz/bash3boilerplate/. We are always more than happy to accept your contributions!
Why are you typing BASH in all caps?
As an acronym, Bash stands for Bourne-again shell, and is usually written with one uppercase. This project's name, however, is "BASH3 Boilerplate". It is a reference to "HTML5 Boilerplate", which was founded to serve a similar purpose, only for crafting webpages. Somewhat inconsistent – but true to Unix ancestry – the abbreviation for our project is "b3bp".
How can I locally develop and preview the b3bp website?
You should have a working Node.js >=10 and Ruby >=2 install on your workstation. When that is the case, you can run:
npm run web:preview
This will install and start all required services and automatically open a webbrowser that reloads as soon as you make any changes to the source.
The source mainly consists of:
./README.md(Front page)./FAQ.md(FAQ page)./CHANGELOG.md(changelog page)./website/_layouts/default.html(the design in which all pages are rendered)./website/public/app.js(main JS file)./website/public/style.css(main CSS file)
The rest is dark magic from which you should probably steer clear. : )
Any changes should be proposed as PRs. Anything added to master is automatically deployed using a combination of Travis CI and GitHub Pages.
You are saying you are portable, but why won't b3bp code run in dash / busybox / posh / ksh / mksh / zsh?
When we say portable, we mean across Bash versions. Bash is widespread and most systems offer at least version 3 of it. Make sure you have that available and b3bp will work for you.
We run automated tests to make sure that it will. Here is some proof for the following platforms:
- Linux
GNU bash, version 4.2.25(1)-release (x86_64-pc-linux-gnu) - OSX
GNU bash, version 3.2.51(1)-release (x86_64-apple-darwin13)
This portability, however, does not mean that we try to be compatible with KornShell, Zsh, posh, yash, dash, or other shells. We allow syntax that would explode if you pasted it in anything but Bash 3 and up.
How do I do Operating System detection?
We used to offer a magic __os variable, but we quickly discovered that it would be hard
to create a satisfactory abstraction that is not only correct, but also covers enough use-cases,
while still having a relatively small footprint in main.sh.
For simple OS detection, we recommend using the ${OSTYPE} variable available in Bash as
is demoed in this stackoverflow post:
if [[ "${OSTYPE}" = "linux-gnu" ]]; then
echo "GNU Linux"
elif [[ "${OSTYPE}" = "darwin"* ]]; then
echo "Mac OSX"
elif [[ "${OSTYPE}" = "cygwin" ]]; then
echo "POSIX compatibility layer and Linux environment emulation for Windows"
elif [[ "${OSTYPE}" = "msys" ]]; then
echo "Lightweight shell and GNU utilities compiled for Windows (part of MinGW)"
elif [[ "${OSTYPE}" = "win32" ]]; then
echo "I'm not sure this can happen."
elif [[ "${OSTYPE}" = "freebsd"* ]]; then
echo "..."
else
echo "Unknown."
fi