=========================== J.U.S.T. Makeself Functions =========================== .. default-domain:: bash A plugin for creating a `makeself executable `_, using a docker container. The features of this plugin are focused on putting :file:`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. .. file:: just_makeself_functions.bsh Most environment variables try to auto determine reasonable defaults, but they can always be overridden and customized. .. env:: MAKESELF_NAME The name of the makeself executable written to :env:`MAKESELF_DIST_DIR`. Default: ``just`` .. env:: MAKESELF_LABEL The makeself internal "label". Not really relevant, as quiet mode is enforced. Default: just_label. .. env:: 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``. .. env:: MAKESELF_DIST_DIR The output directory for the makeself distribution. Default: ``${JUST_PROJECT_PREFIX}_MAKESELF_DIST_DIR`` or else ``${MAKESELF_SOURCE_DIR}/dist`` .. env:: UID_CONTAINER .. env:: 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``. .. env:: VSI_COMMON_JUST_SETTINGS In more complicated projects, the :envvar:`JUST_SETTINGS` variable cannot be auto determined, and must be set via :env:`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 :env:`MAKESELF_SOURCE_DIR` is mounted. .. function:: makeself_defaultify .. command:: makeself_build Build the makeself docker images. .. env:: MAKESELF_IMAGE The name of the makeself docker image. Default: vsiri/makeself:latest .. env:: MAKESELF_VERSION The branch/tag name or SHA of makeself used. Requires version 2.4.3 or newer. .. command:: 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 :command:`makeself_add-git-files` and :command:`makeself_add-files` should be made to add project files. This target should be used in conjunction with :cmd:`makeself_add-git-files` which automatically uses ``.git`` metadata to simplify the extra tar arguments needed, or :cmd:`makeself_add-files` for maximum flexibility. .. seealso:: :cmd:`makeself_add-git-files`, :cmd:`makeself_add-files` .. command:: 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 :command:`makeself_just-project`, project directories are added using :command:`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`` .. rubric:: Example just targets .. code-block:: bash # ``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. ;; .. seealso:: :cmd:`makeself_just-project` :cmd:`makeself_add-git-files` .. command:: 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 :command:`makeself_just-project`, git project directories are added using :command:`makeself_add-git-files` :cmd:`makeself_add-git-files` has many advantages over :cmd:`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`` .. rubric:: Example just targets .. code-block:: bash # ``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" ;; .. seealso:: :cmd:`makeself_just-project` :cmd:`makeself_add-files`