diff --git a/README.md b/README.md index 306af50..4f701db 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,14 @@ A cross-platform [Rez](https://github.com/nerdvegas/rez) production tooling mana +[Read The Docs](https://davidlatwe.github.io/rezup/) + ## Why use rezup -* Simplify Rez venv setup and update process -* Easier to manage Rez tooling +* Easier to setup/update Rez venv +* Easier to install custom Rez extensions (plugins) +* Easier to provide different Rez venv setup for different purpose ## Install @@ -30,24 +33,29 @@ $ pip install -U rezup-api ## Quick start -Call `rezup` in your terminal +Simply calling `rezup` in terminal will suffice. ```shell $ rezup ``` -What will/should happen ? +The command above is a shorthand for `rezup use .main`, which means to enter a Rez venv container named `.main`. Usually you must `rezup add` a new container before you can use it. But default container `.main` will automatically be created if it's not existing yet, for the first time. + +So, what will & should happen after calling `rezup` ? + +1. A most basic recipe will be written into user home directory (`~/rezup.toml`) +2. Default container `.main` will be created with that recipe +3. Wait for it... +4. Bam! A vanilla Rez environment is presented (In subprocess) +5. Try `rez --version` or any `rez` command +6. Once you're done, simply type `exit` to escape. -1. For first time quick-start, calling `rezup` will create a default container -2. So wait for it... -3. Bam! A vanilla Rez environment is presented (In subprocess) -4. Try `rez --version` or any `rez` command -5. Once you're done, simply type `exit` to escape. +As you may have seen, Rez venv is in the container and is deployed with a recipe file. Please visit [Container-Recipe](https://davidlatwe.github.io/rezup/container/#recipe) page for more detail about how you can auth and create a richer container by the recipe. -To know more, please run `rezup --help` or `rezup [COMMAND] --help` for each command's usage. +And for other rezup commands, please run `rezup --help` or `rezup [COMMAND] --help` for each command's usage. ```shell $ rezup --help ``` -Or, [Read The Docs](https://davidlatwe.github.io/rezup/) +Or, visit [Command](https://davidlatwe.github.io/rezup/command/) page. diff --git a/docs/container.md b/docs/container.md new file mode 100644 index 0000000..35c2eac --- /dev/null +++ b/docs/container.md @@ -0,0 +1,224 @@ + +## Structure + +A *container* provides Rez environment from it's *revision*. + +Each container holds at least one virtual environment folder that named by timestamp, which is a *revision*. With that convention, the latest version of environment can be sorted out and used without affecting existing container user. + +``` +~\.rezup # container root + | + + - {container} + | : + : : + : + - {revision} # venv and bin tools lives here + : | + + - {revision} # folder named as timestamp, e.g. 1619780350.58 + | + + - {revision} # take latest when calling `rezup use {container}` + + +``` + +## Remote Container + +To manage Rez venv in production, we may want every machine to have the same Rez venv setup and try keeping them up-to-date. + +For this purpose, a centralized remote container is needed as a guidance for `rezup use` command to pick the right Rez venv setup from there, and create it locally if needed. + +!!! question "How that works ?" + + When calling `rezup use {container}`, if the container has remote set, rezup will find the latest valid revision from remote and see if the same revision exists in local and use it. If not, create a new one by the recipe in that remote revision before use. + + But what if local container contains revisions that doesn't exists in remote ? + + The command `rezup use` always respect remote revision even there's more latest revision exists in local. Unless `rezup use --local` is used and remote will be ignored. + +!!! info "The Difference" + + Both local and remote container have the same structure, the difference is the payload. + + === "Local" + Where the Rez venv actually exists. Can be created by command + ``` + rezup add {container} + ``` + + === "Remote" + Only contains the venv installation manifest file (recipe) `rezup.toml` that uploaded by command + ``` + rezup add {container} --remote + ``` + +!!! tip "Local doesn't have to be in local" + + Local container root can be pointed into network drive, but if that's how it setup, keeps an eye on which Python interpreter is being used or the venv may not be usable. + + +## Recipe + +A recipe file defines how a Rez venv should be built. + +### File Naming + +Recipe files usually be saved to and loaded from user home directory, and should be named with container (if not default container) so that command `rezup add ` could pick it up when creating corresponding container, for example: + +* `~/rezup.toml` for container `.main`, the default +* `~/rezup.dev.toml` for container `dev` +* `~/rezup.test.toml` for container `test` +* `~/rezup.{name}.toml` for container `{name}` + +### File Content + +A recipe file may look like the following example, see below for details about each section. + +```toml +description = "My rez setup" + +[root] +local = false +remote = false + +[dotenv] + +[env] +REZ_CONFIG_FILE = "/path/to/rezconfig.py" +MY_CUSTOMS_ENV = "my value" + +[rez] +name = "rez" +url = "rez>=2.83" # a PyPi version specifier or repository path + +[[extension]] +name = "foo" +url = "~/dev/foo" +edit = true # install this in edit mode (pip --edit) + +[[extension]] +name = "bar" +url = "git+git://github.com/get-bar/bar" +isolation = true # additional venv will be created just for this package +python = 2.7 # the python version for the venv of this package + +[shared] +name = "production" +requires = [ + "pyside2", + "Qt5.py", +] + +``` + + +#### description + +```toml +description = "hello, Rez!" +``` + +Like a comment, for knowing what this recipe is for. + + +#### root + +Define where the root of this container should be. + +```toml +[root] +local = "" +remote = "/studio/remote/.rezup" +``` + +=== "local" + If the value is `false` or empty string `""`, env var `REZUP_ROOT_LOCAL` will be used, or the default `~/.rezup`. + +=== "remote" + If the value is `false` or empty string `""`, env var `REZUP_ROOT_REMOTE` will be used, or no remote for this container. + + +#### dotenv + +The `.env` files will be loaded in order when container revision is being used, if provided. + +```toml +[dotenv] +1 = "/to/my.env" # non platform specific, load firstly, sort by key +2 = "/to/other.env" +[dotenv.linux] +a = "/to/lnx.env" # platform specific, load secondly, sort by key +[dotenv.darwin] +a = "/to/mac.env" # platform specific, load secondly, sort by key +[dotenv.windows] +a = "/to/win.env" # platform specific, load secondly, sort by key +``` + +The key can be anything, they are only for sorting. + + +#### env + +These will be loaded when container revision is being used, if provided. + +```toml +[env] +REZ_CONFIG_FILE = "/path/to/rezconfig.py" +``` + + +#### rez + +Rez venv setup configurations + +```toml +[rez] +# required +name = "rez" +url = "/path/to/source/rez" +# optional +edit = true +flags = ["-E"] +python = 3.7 +``` + +|Name|Required|Description +| :---: | :---: | --- | +|name| O | The name of the package | +|url| O | The url that pass to `pip install`. Could be version specifier like `rez>=2.90`, or from version control like `git+https://github.com/nerdvegas/rez`, or local source path.| +|edit| - | Just like `pip install -e`, install package in edit mode or not. | +|python| - | The Python to create venv with. Use current if not set. Could be path to Python executable, or version | +|flags| - | Python interpreter flags, default `["-E"]` if not set. No flag will be added if the value is an empty list. | + + +#### extension + +```toml +[[extension]] # note this is a list but it's name is not plural +# required +name = "foo" +url = "foo>=0.5" +# optional +edit = false +flags = ["-E"] +isolation = true +python = 3.10 # ignored if `isolation` is false +``` + +Just like the section `rez`, but there's an extra option `isolation` can be used. Shouldn't be needed in most cases though. + +If `isolation` is true, a venv will be created just for this extension with Rez installed as lib into it. If false as default, the extension will be installed into the Rez venv. + + +#### shared + +```toml +[shared] +name = "production" +requires = [ + "pyside2", + "Qt5.py", +] +``` + +For faster deploy, dependency packages can be installed in here, and will be shared across all revisions in one container (all revisions that use same `name` of shared lib). + +This works by creating a `.pth` file that contains the absolute path of shared lib in Rez venv and only that venv. So this will not be shared with the extension that has `isolation` set to true. diff --git a/docs/environ.md b/docs/environ.md index d477287..3646f47 100644 --- a/docs/environ.md +++ b/docs/environ.md @@ -3,8 +3,8 @@ |Name|Description| | --- | --- | -|REZUP_ROOT_LOCAL|Root path of local containers, default is `~/.rezup`| -|REZUP_ROOT_REMOTE|Root path of remote containers| +|REZUP_ROOT_LOCAL|Root path of local containers, if not defined in [Recipe](../container#root), default is `~/.rezup`| +|REZUP_ROOT_REMOTE|Root path of remote containers, if not defined in [Recipe](../container#root)| |REZUP_DEFAULT_SHELL|Specify shell to use. See [Command](../command#shell-detection).| |REZUP_PROMPT|For customizing shell prompt, optional. See [Command](../command#shell-prompt).| |REZUP_CONTAINER|Auto set, for customizing shell prompt. See [Command](../command#shell-prompt).| diff --git a/docs/recipe.md b/docs/recipe.md deleted file mode 100644 index 864e515..0000000 --- a/docs/recipe.md +++ /dev/null @@ -1,84 +0,0 @@ - -To customize the container, you can write a `~/rezup.toml` to tell what should be installed and what environment variable should have. For example : - -```toml -description = "My rez setup" - -[root] -# Where local container is at, supersede $REZUP_ROOT_LOCAL if set -local = false -# Where remote container is at, supersede $REZUP_ROOT_REMOTE if set -remote = false - -# the .env file will be loaded when container revision is being used -[dotenv] -1 = "/to/my.env" # non platform specific, load firstly, sort by key -2 = "/to/other.env" -[dotenv.linux] -[dotenv.darwin] -[dotenv.windows] -a = "/to/win.env" # platform specific, load secondly, sort by key - -[env] -# these will be loaded when container revision is being used -REZ_CONFIG_FILE = "/path/to/rezconfig.py" -MY_CUSTOMS_ENV = "my value" - -[rez] -name = "rez" -url = "rez>=2.83" # a PyPi version specifier or repository path - -[[extension]] -name = "foo" -url = "~/dev/foo" -edit = true # install this in edit mode (pip --edit) - -[[extension]] -name = "bar" -url = "git+git://github.com/get-bar/bar" -isolation = true # additional venv will be created just for this package -python = 2.7 # the python version for the venv of this package - -[shared] -# Packages that will be shared across all revisions in this container, -# except extension that has `isolated` set to true. -name = "production" -requires = [ - "toml", - "pyside2", - "Qt5.py", -] - -``` - -Recipe file name should embed container name (if not default container) so that command `rezup add ` could pick it up when creating corresponding container, for example: - -* `~/rezup.toml` for container `.main`, the default -* `~/rezup.dev.toml` for container `dev` -* `~/rezup.test.toml` for container `test` -* `~/rezup.{name}.toml` for container `{name}` - - - -## How it works ? - -### Container - -A *container* is a Rez environment. And each container holds at least one virtual environment folder named by timestamp, which is *revision*. With that convention, the latest version of environment can be provided without affecting existing user. - -``` -# Container/Revision structure - -\.rezup - | - + - {container} - | | - : + - {revision} # venv and bin tools lives here - : | - + - {revision} # the folder is named as timestamp, e.g. 1619780350.588625 - | - + - {revision} # latest one will be provided when calling `rezup use {container}` in terminal - -``` - -For centralize management in production, one remote container can be defined with env var `REZUP_ROOT_REMOTE`. The remote container only contains the venv installation manifest file `rezup.toml`, and when being asked, a venv revision will be created locally or re-used if same revision exists in local. diff --git a/docs/rezup.md b/docs/rezup.md index 66aca45..ed09637 100644 --- a/docs/rezup.md +++ b/docs/rezup.md @@ -5,6 +5,13 @@ ::: rezup.recipe.ContainerRecipe + +# get_container_root + +*Internal use* + +::: rezup.container.get_container_root + # Container ::: rezup.container.Container diff --git a/docs/scripts.md b/docs/scripts.md index bdad94c..4be735a 100644 --- a/docs/scripts.md +++ b/docs/scripts.md @@ -14,6 +14,8 @@ env = util.resolve_environ(revision, ["pkg_a", "pkg_b"]) !!! tip "Provisional recipes" + By default, all recipe files should be in user home directory and only there will be looked for. But in some cases, you may want to provide your own *remotely*. + ```python from rezup import util, ContainerRecipe diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 68d71af..391d8f5 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -9,6 +9,12 @@ margin-left: 1.2rem; } +.md-typeset ul li, +.md-typeset ol li +{ + margin-left: 2rem; +} + /* For source code summary */ .md-typeset summary diff --git a/mkdocs.yml b/mkdocs.yml index ddde4d0..1e2a841 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -59,7 +59,7 @@ nav: - Home: - Overview: index.md - Usage: - - Recipe: recipe.md + - Container: container.md - Command: command.md - Scripts: scripts.md - Environ: environ.md