Skip to content

Commit

Permalink
Merge branch 'main' into 22-unpacked
Browse files Browse the repository at this point in the history
  • Loading branch information
tomeichlersmith authored Aug 18, 2023
2 parents e53581f + 5dfc542 commit adeee05
Show file tree
Hide file tree
Showing 13 changed files with 188 additions and 22 deletions.
15 changes: 12 additions & 3 deletions .github/workflows/manpages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,26 +4,35 @@ name: Generate Manual

on:
push:
branches:
- 'main'
paths:
- 'docs/src/manual.md'
workflow_dispatch:

jobs:
gen_man:
permissions:
pull-requests: write
contents: write
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- id: generate
run: |
sudo apt-get update
sudo apt-get install pandoc
./man/gen-man
./ci/gen-man
- name: push updated manual
run: |
git config --global user.name denv-docs-bot
git config --global user.email [email protected]
git switch -c auto-man-update
git add man
git commit -m "Auto Man Page Update" || exit 0
git push
git commit -m "Auto Man Page Update from ${{ github.event.head_commit.message }}" || exit 0
git push -fu origin auto-man-update
gh pr create --base main --head auto-man-update --title "Auto Man Page Update" --body "triggered by ${{ github.sha }}"
env:
GH_TOKEN: ${{ github.token }}
2 changes: 1 addition & 1 deletion .github/workflows/mdbook.yml
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ jobs:
run: mdbook build
working-directory: docs
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
uses: actions/upload-pages-artifact@v2
with:
path: ./docs/book

Expand Down
2 changes: 1 addition & 1 deletion _denv_entrypoint
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ if [ ! -f "${HOME}/.denv/skel-init" ]; then
fi

if [ -f "${HOME}/.bashrc" ]; then
if [ "${DENV_RUNNER}" = "singularity" ]; then
if [ "${DENV_RUNNER}" = "singularity" ] || [ "${DENV_RUNNER}" = "apptainer" ]; then
# for apptainer/singularity runners
{
echo "# apptainer/singularity set the environment varible PROMPT_COMMAND"
Expand Down
2 changes: 1 addition & 1 deletion ci/check
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,4 @@ shellcheck \
--color=always \
denv _denv_entrypoint \
install uninstall \
ci/test ci/check
ci/test ci/check ci/set-version
File renamed without changes.
140 changes: 140 additions & 0 deletions ci/set-version
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
#!/bin/sh

set -o nounset
set -o errexit

# update the version in the source files
# ARGS
# 1 - new version X.Y.Z
update() {
# manual source markdown
sed -i "s|denv v.*$|denv v${1}|" docs/src/manual.md
# install script
sed -i "s|^version=v.*$|version=v${1}|" install
# denv itself
sed -i "s|^denv_version=.*$|denv_version=${1}|" denv
}

# check if passed version string is a valid version
# ARGS
# 1 - version string to test
validate_version() {
expr "${1}" : '^[0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*$' > /dev/null
}

# check if there are any changes the user hasn't commited yet
check_changes() {
# checks for any untracked or modified files
git ls-files --other --modified --directory --exclude-standard | sed q1 > /dev/null
}

error() {
printf >&2 "\033[1;31mERROR: \033[0m\033[31m%s\033[0m\n" "$*"
}

inf() {
printf "\033[1mINFO: \033[0m%s\n" "$*"
}

help() {
cat<<\HELP
update the version of denv across all places
USAGE:
./ci/set-version [options] X.Y.Z
ARGUMENTS
X.Y.Z : new version string to use
OPTIONS
-h, --help : print this help and exit
--commit : make a commit, tag, and push
--dry-run : just show what would be done in
a git-diff-like format
--force : ignore if there are untracked
or modified files in your git working tree
HELP
}

if [ "$#" -eq 0 ]; then
help
exit 0
fi

version=""
commit=0
dry_run=0
force=0
while [ "$#" -gt 0 ]; do
case "$1" in
-h|--help)
help
exit 0
;;
--commit)
commit=1
;;
--dry-run)
dry_run=1
;;
--force)
force=1
;;
-*)
error "Unrecognized option '$1'"
exit 1
;;
*)
if [ -z "${version}" ]; then
version="$1"
else
error "./ci/set-version only accepts a single argument"
exit 1
fi
;;
esac
shift
done

if [ -z "${version}" ]; then
error "need to define the version we should use"
exit 1
fi

if ! validate_version "${version}"; then
error "version string '${version}' does not match X.Y.Z"
exit 1
fi

if ! check_changes && [ "${force}" -eq "0" ]; then
error "Some untracked or modified files are still in the git area. Did you commit all the changes?"
exit 1
fi

update "${version}"

# use git diff to print what we changed and then
# show what other commands would be run given the command options
if [ "${dry_run}" -eq "1" ]; then
git diff docs/src/manual.md install denv
if [ "${commit}" -eq "1" ]; then
echo git add docs/src/manual.md install denv
echo git commit -m "set version to v${1}"
echo git tag "v${1}"
echo git push --tags
fi
# undo the changes we made
git restore docs/src/manual.md install denv
exit 0
fi

# down here if not in a dry, run keep the applied changes
if [ "${commit}" -eq "1" ]; then
git add docs/src/manual.md install denv
git commit -m "set version to v${1}"
git tag "v${1}"
git push --tags
fi
6 changes: 3 additions & 3 deletions denv
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
# You should have received a copy of the GNU General Public License
# along with denv; if not, see <http://www.gnu.org/licenses/>.

denv_version=0.2.0
denv_version=0.2.1

# POSIX
set -o errexit
Expand Down Expand Up @@ -297,9 +297,9 @@ _denv_run() {
###################################################################################################

_denv_deduce_workspace() {
# start from PWD and go up directories until file .denv
# start from present working directory and go up directories until find .denv
# or reach root directory
denv_workspace="${PWD}"
denv_workspace="$(pwd -P || true)"
while [ "${denv_workspace}" != "/" ]; do
if [ -d "${denv_workspace}/.denv" ]; then
return 0
Expand Down
5 changes: 5 additions & 0 deletions docs/src/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,18 @@ This is the main origin for `denv` - provide a common interface for using images
a development environment across these four container managers.

## Alternatives
In general, most of these alternatives are either more popular than denv or maintained
by larger groups of people (or both), so I would suggest using one of these projects if
they work for your use case.

- [distrobox](https://github.com/89luca89/distrobox): main inspiration for denv, POSIX-sh program with a larger feature set than denv but currently restricted to docker or podman
- I attempted to develop distrobox in such a way as to support apptainer and singularity; however, the added features mainly centered around editing the container while it is being run were not supported by the apptainer/singularity installations on the HPCs I have access to.
- [VS Code devcontainers](https://github.com/microsoft/vscode-dev-containers): designed to be used in conjuction with the VS Code IDE, also currently restricted to docker (or podman with some tweaking)
- [devpod](https://github.com/loft-sh/devpod): Codespaces but open-source, client-only and unopinionated: Works with any IDE and lets you use any cloud, kubernetes or just localhost docker. Similarly restricted to docker/podman as VS Code devcontainers - focused more on providing a [GitHub Codespaces](https://github.com/features/codespaces)-like service that isn't locked in to VS Code and GitHub.
- [devbox](https://github.com/jetpack-io/devbox): "similar to a package manager ... except the packages it manages are at the operating-system level", a helpful tool based on `nix`, written in `go`
- This is the newest project and probably most closely aligned to my goals; however, it would require understanding how to write NixPkgs for all my dependencies (which is not an easy task given how specialized so many of the packages are) and I am not currently able to functionally install it on the HPCs which use apptainer/singularity.
- [toolbox](https://github.com/containers/toolbox): built on top of `podman`, similar in spirit to distrobox and devbox
- [repro-env](https://github.com/kpcyrd/repro-env): rust-wrapper for `podman`, focused on specifying a manifest file which is then evolved into a lock file specifying SHAs for container images and packages, allows env to only evolve when developer desires.

## Quick Start
Install the latest release on GitHub.
Expand Down
13 changes: 13 additions & 0 deletions docs/src/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,3 +46,16 @@ If the code being developed is anything larger than an extremely small one-line
please open an issue and reference the issue number in your branch name. Generally,
I like the format `<issue_number>-short-title` for example `19-connect-net` was used
when developing network-connection supported related to issue 19.

## Version Control
When changing the `denv` version number, one must change it in three locations.
- `denv` itself at the top
- `install` so future pullers will get the latest version
- `docs/src/manual.md` so the man page is regenerated with the new version number

This is annoying to always have to remember to do, so there is a short shell
script to do this for your.
```
./ci/set-version X.Y.Z
```
which can also commit and push the changes with a tag if you so wish.
8 changes: 8 additions & 0 deletions docs/src/env_dev.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,14 @@ Instead of expecting users to correctly write configurations into
the `.bashrc` in their workspace, one can make heavy use of environment
variables in the image definition.

## apptainer support
Apptainer and singularity take a slightly different approach to
running containers than docker or podman and so there are some
restrictions on the images you should impose to ease this difference.

Take a look at [Docker-Apptainer Compatibility](https://apptainer.org/docs/user/main/docker_and_oci.html#best-practices-for-docker-apptainer-compatibility) in the apptainer docs to learn
more.

## distrobox
This is probably the biggest tip. Remember when I said that distrobox
inspired denv and denv has a smaller feature set? Well, I think distrobox
Expand Down
6 changes: 2 additions & 4 deletions docs/src/manual.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# NAME

denv v0.2.0
denv v0.2.1

# SYNOPSIS

Expand Down Expand Up @@ -159,9 +159,7 @@ means any image that are configured to be used by denv will then be re-downloade

# CONTRIBUTING

Feel free to create a fork of https://github.com/tomeichlersmith/denv and open a Pull Request with any bug patches or feature improvements. We aim to keep denv as a single file with optional completion and manual files in parallel. Check that denv is still POSIX with dash.

dash -n denv
Feel free to create a fork of https://github.com/tomeichlersmith/denv and open a Pull Request with any bug patches or feature improvements. We aim to keep denv as a single file with optional completion and manual files in parallel.

Install shellcheck from https://github.com/koalaman/shellcheck and use it to make sure denv avoids common shell scripting errors.

Expand Down
2 changes: 1 addition & 1 deletion install
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ Options:
EOF
}

version=v0.2.0
version=v0.2.1
next=0
verbose=0
devel=0
Expand Down
9 changes: 1 addition & 8 deletions man/man1/denv.1
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
.hy
.SH NAME
.PP
denv v0.2.0
denv v0.2.1
.SH SYNOPSIS
.PP
\f[B]denv\f[R] version
Expand Down Expand Up @@ -219,13 +219,6 @@ Feel free to create a fork of https://github.com/tomeichlersmith/denv
and open a Pull Request with any bug patches or feature improvements.
We aim to keep denv as a single file with optional completion and manual
files in parallel.
Check that denv is still POSIX with dash.
.IP
.nf
\f[C]
dash -n denv
\f[R]
.fi
.PP
Install shellcheck from https://github.com/koalaman/shellcheck and use
it to make sure denv avoids common shell scripting errors.
Expand Down

0 comments on commit adeee05

Please sign in to comment.