From 8dec9d6396691e2a089a1afa76cd1d6631b23f4e Mon Sep 17 00:00:00 2001 From: Ofek Lev Date: Sun, 31 Dec 2023 18:34:33 -0500 Subject: [PATCH] Add how-to page (#63) * Add how-to page * Update index.md --- docs/how-to.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 2 ++ mkdocs.yml | 1 + 3 files changed, 79 insertions(+) create mode 100644 docs/how-to.md diff --git a/docs/how-to.md b/docs/how-to.md new file mode 100644 index 0000000..908485a --- /dev/null +++ b/docs/how-to.md @@ -0,0 +1,76 @@ +# How-to + +----- + +What follows is a short example showing the end-to-end experience from building an application to running the application as a user. + +## Install Rust + +Follow [the instructions](https://www.rust-lang.org/tools/install) to install Rust and make sure the package manager Cargo is on your PATH. + +## Get PyApp + +In order to [build](build.md) applications with PyApp, you must first download the source code. Here we will download the latest release. + +=== "Linux/macOS" + 1. `curl https://github.com/ofek/pyapp/releases/latest/download/source.tar.gz -Lo pyapp-source.tar.gz` + 2. `tar -xzf pyapp-source.tar.gz` + 3. `mv pyapp-v* pyapp-latest` + 4. `cd pyapp-latest` + +=== "Windows" + 1. `Invoke-WebRequest https://github.com/ofek/pyapp/releases/latest/download/source.zip -OutFile pyapp-source.zip` + 2. `7z x pyapp-source.zip` + 3. `mv pyapp-v* pyapp-latest` + 4. `cd pyapp-latest` + +## Configuration + +You must [configure](config.md) the binaries PyApp produces with environment variables. There are [many ways](examples.md) to configure applications but here we will define a single package to install from PyPI at a specific version: + +| Option | Value | +| --- | --- | +| `PYAPP_PROJECT_NAME` | `cowsay` | +| `PYAPP_PROJECT_VERSION` | `6.0` | + +## Building + +Run: + +``` +cargo build --release +``` + +The executable will be located at `target/release/pyapp.exe` if on Windows or `target/release/pyapp` otherwise. + +## Distribution + +Be sure to rename the binary to the name of the application (and make it executable on non-Windows systems): + +=== "Linux/macOS" + ``` + mv target/release/pyapp cowsay && chmod +x cowsay + ``` + +=== "Windows" + ``` + mv target\release\pyapp.exe cowsay + ``` + +## Runtime + +After you have distributed the binary to the user, they can execute it directly: + +``` +$ ./cowsay -t 'Hello, World!' + _____________ +| Hello, World! | + ============= + \ + \ + ^__^ + (oo)\_______ + (__)\ )\/\ + ||----w | + || || +``` diff --git a/docs/index.md b/docs/index.md index 27efcf1..0418ea7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,6 +13,8 @@ PyApp is a wrapper for Python applications that bootstrap themselves at runtime. ![PyApp example workflow](assets/images/example.gif){ loading=lazy role="img" } +See the [how-to](how-to.md) for a detailed example walkthrough. + ## Features - Easily build standalone binaries for every platform diff --git a/mkdocs.yml b/mkdocs.yml index 04ca32f..537a549 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,6 +45,7 @@ theme: nav: - About: index.md + - How-to: how-to.md - Building: build.md - Configuration: config.md - Runtime behavior: runtime.md