DocsCommunityTestimonialsUsersGitHubTwitterBlogJobs
HomeDocs
DocsCommunityTestimonialsUsersGitHubTwitterBlogJobsTermsPrivacyCookies
TermsPrivacyCookies
Hey! These docs are for version 2.14, which is no longer officially supported. Click here for the latest version, 2.17!

The `repl` goal opens up an interactive Read-Eval-Print Loop that runs in the foreground.

Typically, the REPL is loaded with the transitive closure of the files and targets that the user provided, so that users may import their code and resources in the REPL.

  1. Install your REPL



There are several ways for Pants to install your REPL. See [Installing tools](🔗).

In this example, we simply find the program `bash` on the user's machine, but often you will want to install a tool like Ammonite or iPython instead.

You may want to also add options for your REPL implementation, such as allowing users to change the version of the tool. See [Options and subsystems](🔗).

  1. Set up a subclass of `ReplImplementation`



Subclass `ReplImplementation` and define the class property `name: str` with the name of your REPL, e.g. `"bash"` or `"ipython"`. Users can then set the option `--repl-shell` to this option to choose your REPL implementation.


Then, register your new `ReplImplementation` with a [`UnionRule`](🔗) so that Pants knows your REPL implementation exists:

  1. Create a rule for your REPL logic

Your rule should take as a parameter the `ReplImplementation ` from Step 2, which has a field `targets: Targets` containing the targets specified by the user. It also has a convenience property `addresses: Addresses` with the addresses of what was specified.
Your rule should return `ReplRequest`, which has the fields `digest: Digest`, `args: Iterable[str]`, and `extra_env: Optional[Mapping[str, str]]`. 
The `ReplRequest ` will get converted into an `InteractiveProcess` that will run in the foreground.
The process will run in a temporary directory in the build root, which means that the script/program can access files that would normally need to be declared by adding a `file` / `files` or `resource` / `resources` target to the `dependencies` field.
The process's environment will not be hermetic, meaning that it will inherit the environment used by the `./pants process`. Any values you set in `extra_env` will add or update the specified environment variables.

If you use any relative paths in `args` or `extra_env`, you should call `repl.in_chroot("./example_relative_path")` on the values. This ensures that you run on the correct file in the temporary directory created by Pants.
Finally, update your plugin's `register.py` to activate this file's rules.

Now, when you run `./pants repl --shell=bash ::`, your new REPL should be used.