J.U.S.T. Makeself Functions

A plugin for creating a makeself executable, using a docker container.

The features of this plugin are focused on putting just in a self sufficient executable, for deployment of just and just projects.

A just deploying, referred to as juste (just Executable) allows just to be run without the vsi_common submodule in a project. However, it does require you have juste installed/available on every machine you need it on. No other dependencies are needed, other than bash and common linux core tools like tar, awk and sed.
A “just project executable” is similar to juste, but with one significant difference. It includes all the files of a project with it. This means that the repository for a project is no longer needed to run the project. This makes for a very easy to run deployment strategy. Again, the only dependencies are bash, tar, awk, sed, etc…

Note

Large files should not includes in just project executables. Makeself (quietly) extract the entire contents of the project every time it is run. While this works with in reason, once you start including MBs of files, this time will eventually become noticeable.

The executables made by this plugin put the makeself executables in quiet modes, and the normal argument parsing of makeself is also disabled. This creates a smoother experience for the end user.

Makeself argument parsing can be enabled by exporting MAKESELF_PARSE=true. This can be useful if you ever want to permanently extract the executable, and use the expanded version.

just_makeself_functions.bsh

Most environment variables try to auto determine reasonable defaults, but they can always be overridden and customized.

MAKESELF_NAME

The name of the makeself executable written to MAKESELF_DIST_DIR. Default: just

MAKESELF_LABEL

The makeself internal “label”. Not really relevant, as quiet mode is enforced. Default: just_label.

MAKESELF_SOURCE_DIR

The input directory of the files used to add files to the makeself executable. Default: ${JUST_PROJECT_PREFIX}_MAKESELF_SRC_DIR or else ${JUST_PROJECT_PREFIX}_CWD.

MAKESELF_DIST_DIR

The output directory for the makeself distribution. Default: ${JUST_PROJECT_PREFIX}_MAKESELF_DIST_DIR or else ${MAKESELF_SOURCE_DIR}/dist

UID_CONTAINER

GIDS_CONTAINER

Used to determine user id in container. Should be automatically set by Project’s ${JUST_PROJECT_PREFIX}_UID and ${JUST_PROJECT_PREFIX}_GID, or else uses 1000.

VSI_COMMON_JUST_SETTINGS

In more complicated projects, the JUST_SETTINGS variable cannot be auto determined, and must be set via VSI_COMMON_JUST_SETTINGS.

Set values should start with ${JUST_PATH_ESC}/ and must be in the container’s file system, not hosts. That means it depends on how MAKESELF_SOURCE_DIR is mounted.

makeself_defaultify

just makeself build

Build the makeself docker images.

MAKESELF_IMAGE

The name of the makeself docker image. Default: vsiri/makeself:latest

MAKESELF_VERSION

The branch/tag name or SHA of makeself used. Requires version 2.4.3 or newer.

just makeself just-project

Arguments:

[--tests] - Include unit tests. Calling this from another project is tricky though. For example, ./just --wrap bash -c 'JUSTFILE="${VSI_COMMON_DIR}/Justfile" just test'

Creates a just project executable using makeself. Relative paths will be with respect to ${JUST_PROJECT_PREFIX}_MAKESELF_SRC_DIR. After the initial executable is added, calls to makeself_add-git-files and makeself_add-files should be made to add project files.

This target should be used in conjunction with makeself_add-git-files which automatically uses .git metadata to simplify the extra tar arguments needed, or makeself_add-files for maximum flexibility.

just makeself add-files

Arguments:

$1 - Directory to add
[$2] - Extra tar flags to be passed to makeself/tar

After the initial just executable is created by calling makeself_just-project, project directories are added using makeself_add-files

The second argument can be used to exclude files, and in complicated situations, set up path transforms. * Simple case: ${project_dir}/external/vsi_common * Complicated case: ${project_dir}/external/${other_project}/external/vsi_common

Example just targets

# ``MY_PROJECT_MAKESELF_SRC_DIR`` should be set to ``${MY_PROJECT_CWD}`` in ``my_project.env``

makeself) # Simple case
  justify makeself just-project
  justify makeself add-files "${MY_PROJECT_CWD}" "--exclude .git --exclude ./external/vsi_common"
  ;;

makeself_complicated) # Complicated case
  # First step is the same; it uses your ${JUST_PROJECT_PREFIX}_MAKESELF_SRC_DIR to determine the "main dir",
  # so it can determine the relative path of VSI_COMMON_DIR
  justify makeself just-project

  # The "other project" has a different default settings file.
  # Tell the makeself plugin what it is
  local VSI_COMMON_JUST_SETTINGS=/src/other_project.env
  # Now determine the other project's relative path (again, wrt ${JUST_PROJECT_PREFIX}_MAKESELF_SRC_DIR, which is the same as ".")
  local other_project_rel="$(relative_path "${OTHER_PROJECT_CWD}" .)"
  # Add the other project files
  justify makeself add-files "${OTHER_PROJECT_CWD}" \
    "--show-transformed --transform s|^\./|./${other_project_rel}/| --exclude=.git --exclude=./external/vsi_common"
    # The above transform, makes the files in /src/ appear to be in the
    # "relative" path, determined above

  # Finally add the "main" project files.
  justify makeself add-files "${MY_PROJECT_CWD}" "--exclude .git --exclude ./external/other_project"

  # A neat trick to "exclude all subdirectories except those you want to include"
  # justify makeself add-files "${MY_PROJECT_CWD}" \
  #   "$(find . -mindepth 1 -maxdepth 1 -type d -not -name keep_dir_1 \
  #                                             -not -name keep_dir_2 \
  #                                             -not -name keep_dir_3 -printf ' --exclude %p')"
  # Note: This also includes all the files in the root dir too. This can
  # be customized you your heart's content.
  ;;

just makeself add-git-files

Arguments:

$1 - Directory to add (can be relative or absolute)
[$2] - Extra tar flags to be passed to makeself/tar

After the initial just executable is created by calling makeself_just-project, git project directories are added using makeself_add-git-files

makeself_add-git-files has many advantages over makeself_add-files

No need for you to exclude .git. This is appended to TAR_EXTRA for you
No need to setup the path transform, this is auto determined for you
Only git tracked files are added. Ignored and untracked files are not added. This both simplifies the exclude pattern and prevents accidentally including of large files.

The second argument can still be used to exclude files or pass any other arguments to tar. * Simple case: ${project_dir}/external/vsi_common * Complicated case: ${project_dir}/external/${other_project}/external/vsi_common

Example just targets

# ``MY_PROJECT_MAKESELF_SRC_DIR`` should be set to ``${MY_PROJECT_CWD}`` in ``my_project.env``

makeself) # Simple case
  justify makeself just-project
  justify makeself add-git-files "${MY_PROJECT_CWD}" "--exclude ./external"
  ;;

makeself_complicated) # Complicated case
  # First step is the same
  justify makeself just-project

  # Add the other project files
  justify makeself add-git-files "${OTHER_PROJECT_CWD}" \
    "--exclude=./external/vsi_common"

  # Finally add the "main" project files.
  justify makeself add-git-files "${MY_PROJECT_CWD}" \
    "--exclude ./external/other_project"
  ;;