From 17a69d284a90dd26b8fb82763bf07121b41b16e8 Mon Sep 17 00:00:00 2001 From: Mike Bland Date: Sun, 27 Nov 2016 11:19:37 +0000 Subject: [PATCH 1/2] Add documentation improvements for v1.1.0 release --- README.md | 36 ++++++++++++++++++++++++++++++++++-- lib/bats/assertions | 10 ++++++++-- lib/log | 24 +++++++++++++++++++++++- 3 files changed, 65 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index e843dee..5747a2a 100644 --- a/README.md +++ b/README.md @@ -342,14 +342,46 @@ your scripts directory. Run `./go help plugins` for more information. You can import optional Bash library code from the core framework, third-party plugins, or your own project's scripts directory by sourcing the -`$_GO_USE_MODULES` script. For example, to import the core logging utilities: +`_GO_USE_MODULES` script. For example, to import the core logging utilities: ```bash -. $_GO_USE_MODULES 'log' +. "$_GO_USE_MODULES" 'log' ``` Run `./go help modules` and `./go modules --help` for more information. +#### Logging + +The core library `log` module provides functions for standard logging +facilities. For example: + +```bash +@go.log INFO Hello, World! +@go.log ERROR Goodbye, World! +``` + +For more information, run `./go modules --help log`. + +#### Bats test assertions and helpers + +The assertions and helpers from the test suite have been extracted into the +`lib/bats/assertions` and `lib/bats/helpers` libraries. While these are not +modules you can import with `_GO_USE_MODULES`, they are completely independent +of the rest of the core framework and you may source them in your own Bats +tests. (Whether or not these will ever become a separate library remains an open +question.) + +Read the comments from each file for more information. + +#### `kcov-ubuntu` module for test coverage on Linux + +The `kcov-ubuntu` module provides the `run_kcov` function that will download and +compile [kcov](https://github.com/SimonKagstrom/kcov), then run `kcov` with the +original `./go` command line arguments to collect test coverage. Only available +on Ubuntu Linux for now, hence the name. Run `./go modules --help kcov-ubuntu` +for more information and see `scripts/test` for an example of how it may be +used. + ### Feedback and contributions Feel free to [comment on or file a new GitHub diff --git a/lib/bats/assertions b/lib/bats/assertions index b77a05c..fa46ed8 100644 --- a/lib/bats/assertions +++ b/lib/bats/assertions @@ -24,17 +24,23 @@ # fail "output should not match: '$pattern'" # fi # -# Alternatively, write your own assertion functions starting with: +# Alternatively, write your own assertion function with the following as the +# first line: # # set +o functrace # -# and then make sure every return path calls: +# and then make sure every return path ends with the following (possibly +# followed by a `return` statement, if not at the end of the function): # # return_from_bats_assertion "$return_status" "$BASH_SOURCE" # # You may wish to wrap `return_from_bats_assertion` in a local helper function # to avoid having to specify `$BASH_SOURCE` everywhere. # +# Also note that if your assertion function calls other assertion functions, you +# should call `set +o functrace` after every one of them. See the implementation +# of `assert_lines_equal` for an example. +# # The assertions borrow inspiration from rbenv/test/test_helper.bash. # Unconditionally returns a failing status diff --git a/lib/log b/lib/log index 6ab3444..0746e38 100644 --- a/lib/log +++ b/lib/log @@ -21,7 +21,25 @@ # @go.setup_project # Runs the project's 'setup' script and logs the result # -# See the function comments for each of the above for further information. +# The log level labels are formatted when output to a terminal, and formatting +# can be forced when writing to a pipe or file by setting `_GO_LOG_FORMATTING`. +# +# `@go.log ERROR` will return an error code, so you may use it in conditional +# statements. `@go.log FATAL` will exit the process. +# +# You can pass entire commands to the `@go.log_command` function, which will +# provide log messages upon startup and completion. Upon error, it will log the +# status and return an error code, so you may use it in conditional statements. +# Wrapping blocks of `@go.log_command` invocations in +# `@go.critical_section_begin` and `@go.critical_section_end` will cause any +# errors to log `FATAL`. Setting `_GO_DRY_RUN` will log the commands without +# executing them. +# +# The `@go.setup_project` function provides a convenient wrapper for running +# first-time project setup scripts. It logs the start and finish of the setup +# script, and provides helpful hints on running the `./go` script upon success. +# +# See the function and variable comments from this file for further information. # Set this if you want to force terminal-formatted output from @go.log. # @@ -229,6 +247,10 @@ declare __GO_CRITICAL_SECTION=0 # the critical section flag will be shared between parent and child Bash # scripts. # +# Globals: +# _GO_DRY_RUN: Will log commands without running them +# __GO_CRITICAL_SECTION: Will log FATAL on error +# # Arguments: # $@: The command and its arguments to log and execute @go.log_command() { From e8ef35be43ba717399ba3d25b6b7dc9fb28e2c25 Mon Sep 17 00:00:00 2001 From: Mike Bland Date: Sun, 27 Nov 2016 11:51:29 +0000 Subject: [PATCH 2/2] core: Introduce _GO_CORE_VERSION It only makes sense to export this and make it discoverable via `./go vars`. --- go-core.bash | 24 ++++++++++++------------ tests/vars.bats | 3 +++ 2 files changed, 15 insertions(+), 12 deletions(-) diff --git a/go-core.bash b/go-core.bash index fe76887..0782bbe 100755 --- a/go-core.bash +++ b/go-core.bash @@ -2,9 +2,6 @@ # # Framework for writing "./go" scripts in Bash. # -# Version: v1.0.0 -# URL: https://github.com/mbland/go-script-bash -# # To use this framework, create a bash script in the root directory of your # project to act as the main './go' script. This script need not be named 'go', # but it must contain the following as the first and last executable lines, @@ -35,6 +32,18 @@ if [[ "${BASH_VERSINFO[0]}" -lt '3' || "${BASH_VERSINFO[1]}" -lt '2' ]]; then exit 1 fi +# The version of the framework +# +# NOTE: +# ---- +# This and other variables are exported, so that command scripts written in +# languages other than Bash (and hence run in new processes) can access them. +# See `./go vars` and `./go help vars`. +declare -r -x _GO_CORE_VERSION='v1.0.0' + +# The URL of the framework's original source repository +declare -r -x _GO_CORE_URL='https://github.com/mbland/go-script-bash' + declare __go_orig_dir="$PWD" cd "${0%/*}" || exit 1 @@ -42,12 +51,6 @@ cd "${0%/*}" || exit 1 # # This is directory containing the main ./go script. All functions, commands, # and scripts are invoked relative to this directory. -# -# NOTE: -# ---- -# This and other variables are exported, so that command scripts written in -# languages other than Bash (and hence run in new processes) can access them. -# See `./go vars` and `./go help vars`. declare -r -x _GO_ROOTDIR="$PWD" if [[ "${BASH_SOURCE[0]:0:1}" != '/' ]]; then @@ -104,9 +107,6 @@ declare -x _GO_CMD_NAME= # string with the arguments delimited by the ASCII NUL character ($'\0'). declare -x _GO_CMD_ARGV= -# The URL of the framework's original source repository. -declare -r -x _GO_CORE_URL='https://github.com/mbland/go-script-bash' - # The directory in which plugins are installed. declare _GO_PLUGINS_DIR= diff --git a/tests/vars.bats b/tests/vars.bats index 4010895..4792a11 100644 --- a/tests/vars.bats +++ b/tests/vars.bats @@ -35,6 +35,7 @@ quotify_expected() { 'declare -ax _GO_CMD_NAME=([0]="vars")' "declare -rx _GO_CORE_DIR=\"$_GO_CORE_DIR\"" "declare -rx _GO_CORE_URL=\"$_GO_CORE_URL\"" + "declare -rx _GO_CORE_VERSION=\"$_GO_CORE_VERSION\"" 'declare -a _GO_IMPORTED_MODULES=()' 'declare -- _GO_PLUGINS_DIR=""' 'declare -a _GO_PLUGINS_PATHS=()' @@ -77,6 +78,7 @@ quotify_expected() { 'declare -ax _GO_CMD_NAME=([0]="test-command" [1]="test-subcommand")' "declare -rx _GO_CORE_DIR=\"$_GO_CORE_DIR\"" "declare -rx _GO_CORE_URL=\"$_GO_CORE_URL\"" + "declare -rx _GO_CORE_VERSION=\"$_GO_CORE_VERSION\"" 'declare -a _GO_IMPORTED_MODULES=([0]="complete" [1]="format")' "declare -- _GO_PLUGINS_DIR=\"$TEST_GO_PLUGINS_DIR\"" "declare -a _GO_PLUGINS_PATHS=(${plugins_paths[*]})" @@ -112,6 +114,7 @@ quotify_expected() { "_GO_CMD_NAME: test-command"$'\0'"test-subcommand" \ "_GO_CORE_DIR: $_GO_CORE_DIR" \ "_GO_CORE_URL: $_GO_CORE_URL" \ + "_GO_CORE_VERSION: $_GO_CORE_VERSION" \ "_GO_ROOTDIR: $TEST_GO_ROOTDIR" \ "_GO_SCRIPT: $TEST_GO_SCRIPT" }