Haskell Substitution Stepper

1. Installation

The Haskell Substitution Stepper is distributed as a source code repository and can be installed locally using stack.

Install Steps

Clone the repository from GitLab

cd ~/Downloads/
git clone https://gitlab.ost.ch/haskell-substitution-stepper/substep.git substep

Install the tool

cd substep
stack install

After running the install command, the substep executable is placed into the local binaries directory. To show the local binaries directory path use stack path --local-bin.
The local binaries directory is most likely already part of the PATH environment and the substep command can now be used.
If the substep command is not found, add the local binaries directory to your PATH environment variable. This is a useful guide for how to do this on a linux system.

Help Pages

Running substep --help shows the available sub-commands

substep --help
The Haskell Substitution Stepper

Usage: substep (step | print | list | dump)

Available options:
  -h,--help                Show this help text

Available commands:
  step
  print
  list
  dump

Each sub-command also supports the --help flag to show how to use it:

substep step --help
Usage: substep step (-p|--path STRING) [-f|--function STRING]
                    [-v|--verbose INTEGER]

Available options:
  -h,--help                Show this help text
  -p,--path STRING         The Haskell source file used as input to substep
  -f,--function STRING     Top level function to step through
  -v,--verbose INTEGER     Verbosity level between 1 and 4
  -c,--comments BOOL       Show text comments describing each reduction step

Verbosity Levels

Verbosity Level 1 skips some of the steps and uses a pretty printer that produces a Haskell output.
Verbosity Level 2 does not skip steps and uses a pretty printer that produces a Haskell output.
Verbosity Level 3 skips some of the steps and uses a pretty printer for Haskell Core.
Verbosity Level 4 does not skip steps and uses a pretty printer for Haskell Core.

If no verbosity level is provided, verbosity level 1 is chosen per default.

Project Setup

In order to step a program, substep has to load SteppablePrelude.hs as part of the program that should be stepped. For this, copy the file SteppablePrelude.hs into the same directory as the source file. The setup should look like this:

./testproject
  HaskellSourceFile.hs
  SteppablePrelude.hs

The program can now be stepped:

cd ./testproject
substep step -p HaskellSourceFile.hs

Existing Stack Projects

To use substep with an existing stack project, place the SteppablePrelude.hs into the existing src directory next to the other source files. substep can now be used to step the existing code of the project.

Available Commands

Step

The main function of the stepper. Used to perform the stepwise evaluation of a Haskell program.

substep step -p path/to/<HaskellSourceFile.hs>

Print

Can be used to output the Core stage of the program. Useful to get a better feeling about what is actually being stepped.

substep print -p path/to/<HaskellSourceFile.hs>

List

Shows all the top level bindings of the provided program. The output can include many Core top level bindings that were not present in the Haskell source file. Since the stepper always starts at the top level bindings, this can be a useful summary for what the stepper will step through without actually stepping it.

substep list -p path/to/<HaskellSourceFile.hs>

Dump

Used to dump additional information of the GHC frontend stages used by the stepper. Creates a ./dump directory with the information splitted into various files. Can be used for debugging when something goes wrong.

substep dump -p path/to/<HaskellSourceFile.hs>