Skip to content

Commit

Permalink
Update documentation (#110)
Browse files Browse the repository at this point in the history
  • Loading branch information
ofek authored Apr 21, 2024
1 parent cfe418a commit 45a63f3
Show file tree
Hide file tree
Showing 11 changed files with 274 additions and 257 deletions.
4 changes: 2 additions & 2 deletions docs/build.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

-----

Before building your application, you must configure your [project](config.md#project) at the very least.
Before building your application, you must configure your [project](config/project.md) at the very least.

After you have done that, your application can be built using a [local copy](#local-repository) of this repository or via [installation](#installation) with Cargo.

Expand Down Expand Up @@ -49,4 +49,4 @@ Specific versions may be chosen with the `--version` flag.

Configuration for [cross](https://github.com/cross-rs/cross) is validated by CI to ensure all known environment variable options are passed through to the containers.

When embedding the [project](config.md#project-embedding) or the [distribution](config.md#distribution-embedding) using a local path, you must use the [local repository](#local-repository) way of building and ensure that the configured files to embed reside within the repository and the options refer to relative paths.
When embedding the [project](config/project.md#embedding) or the [distribution](config/distribution.md#embedding) using a local path, you must use the [local repository](#local-repository) way of building and ensure that the configured files to embed reside within the repository and the options refer to relative paths.
225 changes: 0 additions & 225 deletions docs/config.md

This file was deleted.

46 changes: 46 additions & 0 deletions docs/config/cli.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Command line configuration

-----

## Installation indicator

The environment variable that is used for [detection](../runtime.md#detection) may be set to the path of the executable at runtime if you set the `PYAPP_PASS_LOCATION` option to `true` or `1`. This is useful if your application wishes to in some way manage itself.

## Management command

You may set the `PYAPP_SELF_COMMAND` option to override the default name (`self`) of the [management command group](../runtime.md#commands). Setting this to `none` effectively disables the use of management commands.

When enabled, the value will be available at runtime as the `PYAPP_COMMAND_NAME` environment variable.

## Metadata template

You may set a custom template used to [output metadata](../runtime.md#metadata) with the `PYAPP_METADATA_TEMPLATE` option which supports the following placeholders:

| Placeholder | Description |
| --- | --- |
| `{project}` | The normalized project name |
| `{version}` | The currently installed version of the project |

The default template is `{project} v{version}` if this option is unset.

This is useful for setting [custom commands](https://starship.rs/config/#custom-commands) for the [Starship](https://github.com/starship/starship) prompt. The following example configuration assumes that the built executable has been renamed to `foo`:

````toml
format = """
...
${custom.foo}\
...
$line_break\
...
$character"""

# <clipped>

[custom.foo]
command = "foo self metadata"
when = true
## Windows
# shell = ["cmd", "/C"]
## Other
# shell = ["sh", "--norc"]
````
75 changes: 75 additions & 0 deletions docs/config/distribution.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# Python distribution configuration

-----

## Known

Setting the `PYAPP_PYTHON_VERSION` option will determine the distribution used at runtime based on the environment at build time. If unset then the default will be the latest stable minor version of [CPython](#cpython).

### CPython

| ID |
| --- |
| `3.7` |
| `3.8` |
| `3.9` |
| `3.10` |
| `3.11` |
| `3.12` |

The source for pre-built distributions is the [python-build-standalone](https://github.com/indygreg/python-build-standalone) project.

Some distributions have [variants](https://gregoryszorc.com/docs/python-build-standalone/main/running.html) that may be configured with the `PYAPP_DISTRIBUTION_VARIANT` option:

| Platform | Options |
| --- | --- |
| Linux | <ul><li><code>v1</code></li><li><code>v2</code></li><li><code>v3</code> (default)</li><li><code>v4</code></li></ul> |

### PyPy

| ID |
| --- |
| `pypy2.7` |
| `pypy3.9` |
| `pypy3.10` |

The source of distributions is the [PyPy](https://www.pypy.org) project.

## Custom

You may explicitly set the `PYAPP_DISTRIBUTION_SOURCE` option which overrides the [known](#known) distribution settings. The source must be a URL that points to an archived version of the desired Python distribution.

Setting this manually may require you to define extra metadata about the distribution that is required for correct [runtime behavior](../runtime.md).

### Format

The following formats are supported for the `PYAPP_DISTRIBUTION_FORMAT` option, with the default chosen based on the ending of the source URL:

| Format | Extensions | Description |
| --- | --- | --- |
| `tar|bzip2` | <ul><li><code>.tar.bz2</code></li><li><code>.bz2</code></li></ul> | A [tar file](https://en.wikipedia.org/wiki/Tar_(computing)) with [bzip2 compression](https://en.wikipedia.org/wiki/Bzip2) |
| `tar|gzip` | <ul><li><code>.tar.gz</code></li><li><code>.tgz</code></li></ul> | A [tar file](https://en.wikipedia.org/wiki/Tar_(computing)) with [gzip compression](https://en.wikipedia.org/wiki/Gzip) |
| `tar|zstd` | <ul><li><code>.tar.zst</code></li><li><code>.tar.zstd</code></li></ul> | A [tar file](https://en.wikipedia.org/wiki/Tar_(computing)) with [Zstandard compression](https://en.wikipedia.org/wiki/Zstd) |
| `zip` | <ul><li><code>.zip</code></li></ul> | A [ZIP file](https://en.wikipedia.org/wiki/ZIP_(file_format)) with [DEFLATE compression](https://en.wikipedia.org/wiki/Deflate) |

### Python location

You may set the relative path to the Python executable after unpacking the archive with the `PYAPP_DISTRIBUTION_PYTHON_PATH` option. The default is `python.exe` on Windows and `bin/python3` on all other platforms.

### Site packages location

You may set the relative path to the [`site-packages`](https://docs.python.org/3/library/site.html) directory after unpacking the archive with the `PYAPP_DISTRIBUTION_SITE_PACKAGES_PATH` option. The default is `Lib\site-packages` on Windows and `lib/python<ID>/site-packages` on all other platforms where `<ID>` is the defined [distribution ID](#known).

### pip availability

You may indicate whether pip is already installed by setting the `PYAPP_DISTRIBUTION_PIP_AVAILABLE` option to `true` or `1`. This elides the check for installation when [upgraded virtual environments](installation.md#virtual-environments) are enabled.

## Embedding

You may set the `PYAPP_DISTRIBUTION_EMBED` option to `true` or `1` to embed the distribution in the executable at build time to avoid fetching it at runtime.

You can set the `PYAPP_DISTRIBUTION_PATH` option to use a local path rather than fetching the source, which implicitly enables embedding. The local archive should be similar to the [default distributions](#known) in that there should be a Python interpreter ready for use.

## Full isolation

You may set the `PYAPP_FULL_ISOLATION` option to `true` or `1` to provide each installation with a full copy of the distribution rather than a virtual environment.
Loading

0 comments on commit 45a63f3

Please sign in to comment.