One of the first problems our users face today with deploying rez is with installing rez and creating a package for Python. This for us (advanced users) is straightforward, but is something difficult for new users (to rez), users new to package management or users that don't have experience with deploying software.

The reason why it's difficult is that they have to take multiple decisions and it's not always easy to know which one is the best for them.

Installation specific questions:

* Which python should I use to install rez? Should I use python provided by my system (for example on Linux or macOS) or should I use a separate Python?
* How will I be able to get rez to work for the artists?
* Will I be able to share a single install with everyone (so install on a shared filesystem) or will I have to deply rez locally on each workstation and server?
* Which Python version should I use?
* Does it even matter?
* What do I do if my system doesn't even have Python and I can't install Python on the system because of rules imposed by my organization?

Python rez package questions:

* How can I create a package for python?
* Do I really have to compile CPython from scratch?
* Why can't I just use the python from my system?
* Is there any gotchas?

In this document, we will go over what we could do to improve the situation and simplify the "getting started with rez" story.

Non-goals: Replace `install.py` entirely. This script is there to stay for now.

# Requirements

* A simple command line that will let a user install rez even if python is not available on a system.
* The tool must be easy to get and install.
* A system that is portable and supports all platforms.
* Portable in the sense that the tool should have zero dependencies (not even system dependencies).
* Must be easy to use.
* Flexible enough to support a wide variety of use cases
* It must support offline studios.
* It must support installing rez using a specified python version.
* It must support instaling any given rez version.
* Must have sane defaults and be configurable.
* Must be secure by default
* If we provide a single binary executable, it must be signed, have SLSA attestation and must be fully reproducible
* It must use trusted sources to get Python
* Must provide graphviz out of the box since graphviz is central to debug rez issues.

# Proposal

Create a command line that will allow to easily bootstrap rez into a studio.

The tool should be written in compiled memory safe language, either go or rust. Both languages are memory safe and create static executables by default. Statically linked executables don't depend on system dependencies.

We will provide pre-compiled binaries.

## Functionalities

### Download a pre-compiled python

The tool should allow to download any python versions that a user could need.
This is not a simple task though.

For Windows, we could use [nuget's python package](https://www.nuget.org/packages/python) which is an official CPython distribution maintained by CPython core developers and Microsoft employees. It provides a fully working and fully relocatable python interpreter that doesn't require any installaion.

On *nix systems, it's a much harder problem to solve. On Linux for example, one has to consider glibc's version and other system libraries. macOS provides its own challenges too.

In the last couple of years (2 years, maybe 3), [python-build-standalone](https://github.com/indygreg/python-build-standalone) was invented. Their goal is to produce redistributable builds of CPython on all platforms. Very recently (2024), it started to be used by tools such as [uv](https://github.com/astral-sh/uv), [rye](https://github.com/mitsuhiko/rye) and others.

`python-build-standalone` is not perfect, but I think it should be enough for plenty of cases.

This python can be used to create the rez installation. It can also be used to create the `python` rez package.

### List available components (rez, python, etc)

List components (versions) available to download and install. This is fairly simple. We should strive to choose the right versions for our users, but we can also give them a way to list what's available and manually choose what to install.

For example, `python-build-standalone` provides multiple flavors of builds per python version. They have optimized builds, builds that support only some CPU micro-architectures (`x86_64`, `x86_64_v2`, `x86_64_v3`, `x86_64_v4`). Because rez is often installed centrally, we can't know what a studio will need.

### Provide easy access to Graphviz

Of all the problems our users face today with deploying rez, this is probably the most troublesome.

Rez relies on the `dot` executable provided by Graphviz to do some of its operations. For example, [rez-context \--graph](https://rez.readthedocs.io/en/stable/commands/rez-context.html#cmdoption-rez-context-g) and [rez-env \--fail-graph](https://rez.readthedocs.io/en/stable/commands/rez-env.html#cmdoption-rez-env-fail-graph) rely on `dot` to produce an image of the graph.

This is of-course optional, but it's a vital part of rez. Without this, it's very difficult to debug anything in rez. And graphviz is a tool that is quite hard to replace with something else. Alternatives often rely on much heavier dependencies like Java or a JavaScript engine.

I think we could compile graphviz ourselves on all platforms with only the absolute minimum dependencies required. After all, we only need a very tiny portion of graphviz. More investigation will have to be done to see if it's a viable option or not. **We also have to consider the license**.

We could also consider using graphviz WASM bindings and do the rendering in a browser. For example, we could use https://hpcc-systems.github.io/hpcc-js-wasm/classes/graphviz.Graphviz.html to render the SVG in a browser. We would simply have to build a simple HTML page that contains the DOT graph instead of rendering straight to PNG or SVG. This would open the door for interactive graphs. An example can be seen at https://raw.githack.com/hpcc-systems/hpcc-js-wasm/trunk/index.html.

There is also https://github.com/mdaines/viz-js.

https://sporks.space/2023/04/11/building-a-static-graphviz-for-macos/

### Bootstrap core packages

The tool must provide a way to create the `arch`, `os` and `platform` packages. As oposed to `rez-bind`, it must allow the user to create the packages in a generic way (i.e. it should not rely on the current machine and should allow to cross-create them for other machines).

# python-build-standalone gotchas

## Minimum glibc and macOS SDK

`python-build-standalone` is great, but it's also annoying for some things. For example, they don't easily provide information on the minimum glibc required on Linux, or the minimum macOS version. Though, luckily, this information is available. It just requires more work. It can be found in the `python/PYTHON.json` file of the "full" flavors.

## Licenses

Because of their very nature, the interpreters provided by `python-build-standalone` have some license requirements which need to be taken into consideration.

See https://gregoryszorc.com/docs/python-build-standalone/main/running.html#licensing.

# CLI

## rezup

Main command to manage rez.

usage: rezup [-h] [--version] {install,update,package} ...

Manage a rez installation

positional arguments:
  {bootstrap,install,update,package}
    bootstrap           bootstrap a rez ecosystem
    install             install rez
    update              update rez
    package             package

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit

## rezup bootstrap

Command to easily bootstrap a rez ecosystem. This can be viewed as a "super command"
that calls out to other commands.

It will install rez and create the `arch`, `os` and `platform` packages. It will also optionally create a `python` package.

The command can take inputs through stdin or can be driven through CLI flags.

usage: rezup bootstrap [-h]

options:
  -h, --help  show this help message and exit

## rezup install

Install rez.

* Automatically adds rez to `$PATH`. The command will prompt the user.

usage: rezup install [-h] [--python-version] [version] path

positional arguments:
  version            version to install
  path               path to install rez into

options:
  -h, --help         show this help message and exit
  --python-version   python version to use to install rez

## rezup update

Update a rez installation.

## rezup package

Operations on basic rez packages (bootstrap).

usage: rezup package [-h] {install,list} ...

positional arguments:
  {install,list}
    install       install package
    list          list packages

options:
  -h, --help      show this help message and exit

## rezup package install

Install a rez package.

usage: rezup package install [-h] {os,arch,platform,python,graphviz}

positional arguments:
  {os,arch,platform,python,graphviz}
                        Package to install

options:
  -h, --help            show this help message and exit

## rezup package list

List available packages.

usage: rezup package list [-h] [{os,arch,platform,python,graphviz}]

positional arguments:
  {python,os,arch,platform,graphviz}
                        only list versions of this package

options:
  -h, --help            show this help message and exit

## rezup self update

Self update rezup. **Should we have this?**