Skip to content

[On hold until RDK release] Document --from-source flag for module build start #5136

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Shannon Bradshaw (shannonbradshaw) wants to merge 1 commit into
base: main
Choose a base branch
from
Open

[On hold until RDK release] Document --from-source flag for module build start #5136

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/build-modules/deploy-a-module.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,9 @@ With prep complete, follow one of the two sections below to publish your module.

### Publish with cloud build (recommended) {#release-with-cloud-build}

Cloud build is a Viam-side build service that compiles your module from your GitHub repo for every target platform listed in `meta.json`'s `build.arch`. Both paths below require your module to be in a GitHub repo with the URL set in `meta.json`.
Cloud build is a Viam-side build service that compiles your module for every target platform listed in `meta.json`'s `build.arch`. By default, cloud build clones your GitHub repo. Both default-mode paths below require your module to be in a GitHub repo with the URL set in `meta.json`.

Alternatively, pass `--from-source` to upload your local source directory directly to the cloud builder without requiring a GitHub repo or a git push. See the [CLI reference](/cli/reference/#module-build-start) for the full flag list.

If you don't have a GitHub repo yet, push your module's code to one. From your module's root directory:

Expand Down
4 changes: 3 additions & 1 deletion docs/build-modules/module-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -473,7 +473,9 @@ All module CLI commands are under `viam module`. You must be logged in
| `viam module build logs --id <build-id>` | Stream logs from a cloud build job. |

`build start` flags: `--ref` (git ref, default: `main`), `--platforms`,
`--token` (for private repos), `--workdir`.
`--token` (for private repos), `--workdir`, `--from-source` (upload local
source instead of building from a git ref), `--path`, `--wait`,
`--no-progress`.

During builds, the environment variables `VIAM_BUILD_OS` and `VIAM_BUILD_ARCH`
are set to the target platform. See [Environment variables](#environment-variables).
Expand Down
6 changes: 6 additions & 0 deletions docs/cli/build-and-deploy-modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,12 @@ Build from a specific git ref:
viam module build start --version=1.0.0 --ref=main
```

Build from your local source directory without pushing to GitHub first:

```sh {class="command-line" data-prompt="$"}
viam module build start --version=1.0.0 --from-source --platforms=linux/amd64,linux/arm64 --wait
```

Build locally to test before pushing:

```sh {class="command-line" data-prompt="$"}
Expand Down
11 changes: 9 additions & 2 deletions docs/cli/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1911,6 +1911,9 @@ viam module build start --version "0.1.2"

# initiate a cloud build for a private GitHub repo
viam module build start --version "0.1.2" --token ghp_1234567890abcdefghijklmnopqrstuvwxyzABCD

# build from local source without pushing to GitHub
viam module build start --version "0.1.2" --from-source --platforms linux/amd64,linux/arm64 --wait
```

<!-- prettier-ignore -->
Expand All @@ -1919,9 +1922,13 @@ viam module build start --version "0.1.2" --token ghp_1234567890abcdefghijklmnop
| `--version` | The version of your module to set for this build. See [Using the `--version` argument](#using-the---version-argument). | **Required** |
| `--module` | The path to the [`meta.json` file](/build-modules/module-reference/) for the module, if not in the current directory. | Optional |
| `--platforms` | List of platforms to cloud build for. Default: `build.arch` in <file>meta.json</file>. | Optional |
| `--ref` | Git reference to clone when building your module. This can be a branch name or a commit hash. Default: `main`. | Optional |
| `--token` | GitHub token with repository **Contents** read access, and **Actions** read and write access. Required for private repos, not necessary for public repos. | Optional |
| `--ref` | Git reference to clone when building your module. This can be a branch name or a commit hash. Default: `main`. Ignored when `--from-source` is set. | Optional |
| `--token` | GitHub token with repository **Contents** read access, and **Actions** read and write access. Required for private repos, not necessary for public repos. Ignored when `--from-source` is set. | Optional |
| `--workdir` | Use this to indicate that your <file>meta.json</file> is in a subdirectory of your repo. `--module` flag should be relative to this. Default: `.`. | Optional |
| `--from-source` | Package your local source directory and upload it to the cloud builder instead of building from a git ref. `.gitignore` is honored when packaging. | Optional |
| `--path` | Path to the local source directory to upload. Only used with `--from-source`. Default: `.`. | Optional |
| `--wait` | Wait for the build to finish. Surfaces failed-platform logs and returns a non-zero exit code on failure. Only used with `--from-source`. | Optional |
| `--no-progress` | Hide the progress spinner. Only used with `--from-source`. | Optional |

### `module build local`

Expand Down
Loading