Skip to content

Commit

Permalink
Update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@mottosso
mottosso committed Jul 31, 2019
1 parent b7b16f3 commit 658b57c
Show file tree
Hide file tree
Showing 5 changed files with 26 additions and 152 deletions.
3 changes: 3 additions & 0 deletions docs/pages/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,9 @@ Notice that it isn't unlike a profile, and in fact not unlike any other software

I've talked a lot about "packages" and how great they are, but what exactly *are* they and why should you care?

!!! note "WIP"
I just noticed this section was not filled out yet. Stay tuned. :)

<br>

### Your first profile
Expand Down
1 change: 1 addition & 0 deletions docs/pages/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ template: landing.html
<br>
<img src=https://img.shields.io/pypi/pyversions/allzpark?color=steelblue>
<img src=https://img.shields.io/pypi/v/bleeding-rez?color=steelblue&label=bleeding-rez>
<img src="https://img.shields.io/pypi/v/allzpark">
</p>
<div class="container">
<p id="description">
Expand Down
23 changes: 22 additions & 1 deletion docs/pages/shells.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -210,7 +210,28 @@ Things to be aware of when using Rez with `cmd`.

It isn't quite as simple as that, as there is a limit in the Windows API, another limit in `conhost.exe` and yet another in `cmd.exe`. When using Rez with `cmd.exe`, it is this limit you must take into consideration, and it is the most limiting of them all.

### History
Why does the `cmd.exe` limit apply? It's because whenever you `execute_shell` or enter into a context using `rez env`, Rez is creating a `.bat` script with a series of commands that look like this.

```bash
set PATH=c:\some\path;%PATH%
set PATH=c:\some\other\path;%PATH%
set PATH=c:\yet\another\path;%PATH%
...
```

With one line of `set` for every call to `env` from within your `package.py:commands()` function. And this is where the problem lies, for you see launching `cmd` with a environment containing values longer than 2,000 characters work fine.

```python
import subprocess
subprocess.Popen("cmd", env={"a": "really", "long": "environment"})
# Works
```

But `cmd.exe` itself has issues handling anything longer than 2,000 characters which is why one of those lines of `set` will eventually stop growing.

<br>

### Command-line history

A normal Rez context generates [a deep process hierarchy](../windows#process-tree).

Expand Down
93 changes: 0 additions & 93 deletions docs/pages/windows.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -106,102 +106,9 @@ Set-ItemProperty -Path HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem -Name L
This would effectively prepend `\\?\` to every path "under the hood", solving the issue. But at what cost?

Let the community know if you encounter any issues by making [an issue](https://github.com/mottosso/allzpark/issues/new).
<br>

## Long Environment Variables

See [Shells](../shells#long-environment-variables) for things to keep an eye on with regards to environment variables.

To work around this issue, it is recommended that you use PowerShell on Windows.

**Environment variable**

```powershell
REZ_DEFAULT_SHELL=powershell
```

**rezconfig.py**

```powershell
default_shell = "powershell"
```

<br>

#### Advanced

Why does the `cmd.exe` limit apply? It's because whenever you `execute_shell` or enter into a context using `rez env`, Rez is creating a `.bat` script with a series of commands that look like this.

```bash
set PATH=c:\some\path;%PATH%
set PATH=c:\some\other\path;%PATH%
set PATH=c:\yet\another\path;%PATH%
...
```

With one line of `set` for every call to `env` from within your `package.py:commands()` function. And this is where the problem lies, for you see launching `cmd` with a environment containing values longer than 2,000 characters work fine.

```python
import subprocess
subprocess.Popen("cmd", env={"a": "really", "long": "environment"})
# Works
```

But `cmd.exe` itself has issues handling anything longer than 2,000 characters which is why one of those lines of `set` will eventually stop growing.

<br>

## Platform map

You'll want to use a brutal [`platform_map`](https://github.com/mottosso/bleeding-rez/wiki/Configuring-Rez#platform_map) for your Windows setup, because of stunts like this.

**Machine A**

```bash
$ C:\Users\marcus\Desktop>systeminfo | findstr /B /C:"OS Name" /C:"OS Version"
OS Name: Microsoft Windows 10 Pro
OS Version: 10.0.17134 N/A Build 17134
$ python
>>> import platform
>>> platform.platform()
'Windows-8-6.2.9200'
>>> from rez.utils.platform_ import platform_
>>> platform_.os
'windows-6.2.9200'
```

**Machine B**

```bash
$ C:\Users\marcus\Desktop>systeminfo | findstr /B /C:"OS Name" /C:"OS Version"
OS Name: Microsoft Windows 10 Pro
OS Version: 10.0.18362 N/A Build 18362
$ python
>>> import platform
>>> platform.platform()
'Windows-10-10.0.18362'
>>> from rez.utils.platform_ import platform_
>>> platform_.os
'windows-10.0.18362.SP0'
```

**rezconfig.py**

For a `platform_map`, try this. It'll make any modern version of Windows (8-10) look like Windows 10.

```py
platform_map = {
"os": {
r"windows-6(.*)": r"windows-10",
r"windows-10(.*)": r"windows-10",
},
}
```

This then applies to `rez env` and friends whenever the implict `~os` package is requested. Sadly, this has to happen early in your package repository authoring days, as variants being created also use this value. If a variant has been created using `os-windows-10.0.1803` then that value will have been made into a physical folder on disk that cannot (or should not) change. If the implicit request is then changed to `os-windows-10`, then none of your existing packages with this variants will work.

- [Related issue](https://github.com/mottosso/bleeding-rez/issues/61)

## Process Tree

Virtualenv is one way of using Rez on Windows, and if you do then the `rez.exe` executable is generated during `pip install` and works by spawning a `python.exe` process, also generated by `pip`, which in turn calls on your system `python.exe`. Here's what spawning your own Python session from within a Rez context looks like.
Expand Down
58 changes: 0 additions & 58 deletions docs/theme/landing.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,64 +13,6 @@
<link href="https://fonts.googleapis.com/css?family=Roboto:400,500|Source+Code+Pro" rel="stylesheet">
{% endblock %}

{% block header %}

<header class="md-header" data-md-component="header">
<nav class="md-header-nav md-grid">
<div class="md-flex">
<div class="md-flex__cell md-flex__cell--shrink">
<a href="{{ config.site_url | default(nav.homepage.url, true) | url }}" title="{{ config.site_name }}" class="md-header-nav__button md-logo">
{% if config.theme.logo.icon %}
<i class="md-icon">{{ config.theme.logo.icon }}</i>
{% else %}
<img src="{{ config.theme.logo | url }}" width="24" height="24">
{% endif %}
</a>
</div>
<div class="md-flex__cell md-flex__cell--shrink">
<label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
</div>
<div class="md-flex__cell md-flex__cell--stretch">
<div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
{% if config.site_name == page.title %}
{{ config.site_name }}
{% else %}
<span class="md-header-nav__topic">
{{ config.site_name }}
</span>
<span class="md-header-nav__topic">
{% if page and page.meta and page.meta.title %}
{{ page.meta.title }}
{% else %}
{{ page.title }}
{% endif %}
</span>
{% endif %}
</div>
</div>
<div class="md-flex__cell md-flex__cell--shrink">
{% if "search" in config["plugins"] %}
<label class="md-icon md-icon--search md-header-nav__button" for="__search"></label>
{% include "partials/search.html" %}
{% endif %}
</div>

<p id="pypiBadge">
<img src="https://img.shields.io/pypi/v/allzpark?style=flat-square">
</p>

{% if config.repo_url %}
<div class="md-flex__cell md-flex__cell--shrink">
<div class="md-header-nav__source">
{% include "partials/source.html" %}
</div>
</div>
{% endif %}
</div>
</nav>
</header>
{% endblock %}

{% block site_nav %}
{% if nav %}
<div class="md-sidebar md-sidebar--primary landing" data-md-component="navigation">
Expand Down

0 comments on commit 658b57c

Please sign in to comment.