Skip to content

Home

Jump to bottom
Dewayne VanHoozer edited this page Jun 19, 2022 · 21 revisions

JUST

Casey's just utility is such a useful tool; but, it has one thing that bothered me - the inability to inherently include recipes from other files. For those of us who work on many projects in parallel the ability to share recipes (effective code reuse / modularization) is an important feature. Its advantages are:

  • provides for smaller more easily maintained files
  • more cohesive file content
  • shared recipes between projects

Allowing this flexibility also opens up some use cases which are not currently supported by the just utility. That is why I created the justprep program.

justprep ...

... is a ore-processor to the just command/task runner. It provides the ability to include other just file content into your main just file using a set of keywords that you define. It also adds a short-hand way of specifying modules that are accessible from your main just file.

Configuration

justprep is configured using System Environment Variables

  • JUSTPREP_KEYWORDS specifies the inclusionary keywords that you want to use.
  • JUSTPREP_MODULE_KEYWORD also allows you to specify the keyword that defines a module
  • JUSTPREP_FILENAME_IN defines the basename of files to look for that contain justprep keywords.
  • JUSTPREP_FILENAME_OUT defines the basename of the file that justprep creates from its input files. Typically this value is "justfile" which is the default of the just program.

Installation

There are two implementations of justprep available. The Ruby Gem version and the compiled Crystal version. See Ruby And Crystal for some details.

The Ruby Gem version should be able to run on any platform that has Ruby installed.

Why two implementations? Is there a performance difference? I can't tell if there is any speed difference between the two. It there is it is so small its not worth mentioning.

The reason there are two implementation are 1) I'm researching automatic conversion of Ruby source code into compilable Crystal code; and 2) some organizations which use just are not (shutter) using Ruby. Did I really call them dinosaurs?

Quick aside. For CPU intensive tasks, the compiled Crystal versions of some of my simple Ruby projects is over 30 times faster than thier Ruby prototypes.

As a Ruby Gem

justprep is a command line utility. There is no need to include it in a Gemfile. Just do:

gem install justprep

Crystal Binary Implementation

MacOS

The simpliest way on a MacOS platform is to use brew

brew install justprep

Or you could download the latest release. See the [Precompiled Binaries] section below.

Compile Crystal Implementation from Source

Clone or fork the repository and compile.

Easiest way to compile the Crystal implementation is using the just utility. You do have just installed right?

From the repository root (RR) directory do:

just build

This will build both the Ruby gem implementation and the Crystal implementation. If you only want to build the Crystal version do:

cd crystal
just build

Other useful recipes are available in the justfile supplied with the repository. To see a list of those recipes just(sic) do:

just

Precompiled Binaries

Binary releases are available at https://github.com/MadBomber/justprep/releases/latest they are currently compiled for macos and linux (on the x86_64 architecture).

You should be able to download the binaries and use them directly.

# Download the matching binary from https://github.com/MadBomber/justprep/releases/latest
$ chmod a+x justprep-*
$ mv justprep-* ~/.bin/justprep # or other appropriate directory

Useful Shell Alias

I use the bash shell where I have jj defined as a command executes justprep and then just like this:

alias jj='/usr/local/bin/justprep && just --no-dotenv'

I use the program direnv which defines environment variables via a .envrc file whenever I cd into a directory. That is why I use the "--no-dotenv" option for the just program.

... and yes. I use the Crystal implementation of justprep rather than the Ruby gem implementation even though they are both the same. See Ruby And Crystal for details on why there are two implementations.

~/.justfile

I have a common just file that I include into all of my project specific just files. I keep it in my $HOME directory. .justfile is the filename. It provides a common list/help pattern that I like to use.

In my project just files I do this as the first "executable" line:

include ~/.justfile

My ~/.justfile looks something like this ...

# ~/.justfile
# brew install just
# gem install justprep OR brew install justprep for the Crystal version
# alias jj='justprep && just'
#
# See: https://cheatography.com/linux-china/cheat-sheets/justfile/
#

set positional-arguments    := true
set allow-duplicate-recipes := true
set dotenv-load             := false

pwd         := env_var('PWD')

me          := justfile()
home        := env_var('HOME')
backup_dir  := env_var('JUST_BACKUP_DIR')
backup_file := trim_start_match(me, home)
my_backup   := backup_dir + backup_file

# List available recipes
@list:
  echo
  echo "Available Recipes at"
  echo "$PWD"
  echo "are:"
  echo
  just -l --list-prefix 'jj ' --list-heading ''
  echo

# Show help/usage for "just" command
help: list
  echo
  echo
  just --help

# Backup all changed just files to $JUST_BACKUP_DIR
@backup_all_just_files:
  backup_just.rb

#################################################
## Private recipies

# Show private recipies
@_show_private:     # Show private recipies
  grep "^[@]_" {{justfile()}}

# Show the differents between this justfile and is last backup
@_just_diff_my_backup:
  @diff {{me}} {{my_backup}}

@_just_restore_me_from_backup:
  echo
  echo "Do this because I will not ..."
  echo
  echo "cp -f {{my_backup}} {{me}}"
  echo

# Edit the $JUSTPREP_FILENAME_IN file
@_just_edit_me:
  $EDITOR {{me}}

You may have noticed the backup/restore recipes. I do not always keep my just files in the repository. Sometimes I treat them like my engineering note files. BUT I always want to have backups of the just files and the notes files available just in case I mess stuff up. Of course it would be much easier to just commit them to the git repo but sometimes its nice to have a competitive advantage that is not shared with the rabble.

Clone this wiki locally