R and Python packages¶
This page is for teams who write R or Python packages for their colleagues. A workspace with a
package repository publishes a package with the same velonde deploy that deploys an app. Every
session and every app build of the workspace can then install it like a package from CRAN or PyPI.
Your workspace admin adds the repository (The overlay
shows how). On a workspace without one, velonde deploy of a package says so.
Publish an R package¶
- Create the package, or open an existing one.
velonde::new_app("mypkg", template = "package")creates a package with an example function, its documentation, a test and aCLAUDE.mdwith the conventions. In RStudio, use File > New Project > New Directory > Velonde project and choose the templatepackage. - Set
VersioninDESCRIPTIONand add a line toNEWS.mdfor what changed. - Run
velonde deployin the package directory (in R:velonde::deploy()).
The workspace builds the package in the cluster. It installs the dependencies that DESCRIPTION
lists under Depends, Imports, LinkingTo and Suggests, runs R CMD build, and runs
R CMD check when velonde.yaml contains check: true. A check that ends with an error stops the
publication. The workspace then publishes the source package and a binary for the R version and the
Ubuntu release of the workspace's images, so that installing it takes seconds even when it has
compiled code. The output of every step appears in your terminal, and the last line names the
package and the version that was published.
The first deploy writes a velonde.yaml next to DESCRIPTION and adds it to .Rbuildignore, so
that R CMD check does not report it.
Publish a Python package¶
- Create the package with
uv init --lib mypkg, or open an existing one.pyproject.tomlneeds a[build-system], a fixedversionand alicensein[project], for examplelicense = "MIT". The repository refuses a package without a license. - Raise
versioninpyproject.tomlfor every release. - Run
velonde deployin the project directory.
The workspace runs uv build and publishes the source distribution and the wheel. With
check: true in velonde.yaml, it first runs the tests with pytest, and a failing test stops
the publication.
How the workspace recognises a package¶
A directory with a DESCRIPTION that names a package and a NAMESPACE is an R package. A
directory with a pyproject.toml that has [project] and [build-system] is a Python
package. Both hold only if the directory does not also contain the files that make it an app,
such as app.R or app.py. A Shiny app written as a package, for example with golem,
therefore stays an app. To publish such a directory as a package, set type: package (R) or
type: package-python in its velonde.yaml.
Names and versions¶
A package keeps the name in its DESCRIPTION or pyproject.toml. On the workspace, its name is
that name in lower case with dots and underscores replaced by dashes, so data.table would be
data-table. The commands velonde history, velonde owner and velonde delete accept either form. A
package cannot have the same name on the workspace as an app or as a package of the other language.
Each deploy publishes the version that the package declares, and a published version is never
replaced, because apps may already have installed it. To publish a change, raise the version
first. velonde deploy refuses a version that is already published before it starts the build.
There is no rollback for a package. To undo a release, publish the previous code under a new
version. velonde delete removes a package with all its versions and frees its name, but the workspace
remembers the version numbers and refuses them from then on, whoever publishes the name next.
A lock file names a version, and it must not restore other code under the same number. Every published version stays installable, for example with
renv::install("mypkg@0.1.0") or uv add "mypkg==0.1.0".
The workspace refuses an R package whose name CRAN has, and a Python package whose name PyPI (or your workspace's own Python index) has. R and pip install the highest version that any repository offers, so they would install the other package in place of yours. Rename the package in that case.
Install a package¶
In R, install.packages("mypkg") installs the newest version. The workspace's repository is named
internal and is listed after CRAN in getOption("repos"). In an renv project,
renv::install("mypkg") and renv::snapshot() record the package in renv.lock with
Repository: internal. When you deploy an app with that lock file, the build restores the
package from the workspace's repository like any CRAN package.
In Python, uv add mypkg finds the package in every IDE: the workspace's index is set as an
additional index for uv (UV_INDEX), which looks there before PyPI. uv.lock records where
each package came from, and the build of an app restores it from there. The index is not set
for pip. pip installs the highest version that any of its indexes offers, so a package of the
same name on PyPI could take the place of yours.
Inside the workspace, from IDE sessions, apps and builds, the repository needs no credential. To install from your own computer or from CI, see Install from outside the workspace.
Browse the packages¶
The tile Packages under On this workspace on the workspace's landing page opens the repository's
web interface, and velonde deploy prints its address after it has published a package. It lists
every package with its versions, its description and documentation, who published each version
and when. You are logged in as yourself. Everyone can look; workspace admins can also deactivate or
delete a version there. Publishing goes through velonde deploy, so that the workspace's rules on owners,
versions and names always apply.
Install from outside the workspace¶
velonde packages token in an IDE session creates a personal token for reading the repository
from elsewhere, and prints the settings for R, pip and uv with the token in them, for example:
options(repos = c(getOption("repos"),
internal = "https://token:velondepkg_...@apps.velonde.example.com/packages/internal"))
install.packages("mypkg")
The token reads every package of the workspace, so keep it like a password. It works for a year,
or for the number of days you give with --days. A new velonde packages token replaces your
previous one, which stops working, and velonde packages token --revoke withdraws it. From outside the workspace, R
gets the source packages and compiles them; the binaries are for the workspace's own Linux images.
System libraries¶
The workspace looks up the system libraries that CRAN packages need. For an R package of your own,
name what it needs under system-packages in its velonde.yaml, for example [libxml2-dev]. The
package's build installs them, and so does the build of every app whose lock file contains the
package. velonde sysreqs in an app directory shows them.
Who may publish¶
The user who publishes a package first owns it. As for apps, the owner can name colleagues
under maintainers or maintainer-groups in the package's velonde.yaml, and they may then
publish new versions. A package can also follow a branch of a git repository with
velonde git bind, as described in Deploying from a repository. Every push then publishes
the version it declares, and a push that does not raise the version fails with a message in
velonde git status. Only the owner and workspace admins may delete a package. velonde delete mypkg
removes every version from the repository. Apps that were built with it keep working, but a
new deploy of such an app fails until its lock file no longer needs the package.
When the build fails¶
| Message in the build output | What to do |
|---|---|
there is no package called '...' while building or checking |
Add the package to Imports or Suggests in DESCRIPTION. |
CRAN has a package called ... or ... has a package called ... |
Rename the package. |
... is published already |
Raise the version in DESCRIPTION or pyproject.toml. |
the package repository needs a license |
Add license = "..." to [project] in pyproject.toml. |
| A compiler or linker error that names a missing header or library | Add the Ubuntu package that provides it under system-packages in velonde.yaml. |
R CMD check reports an ERROR, or a test fails |
Fix it locally with devtools::check() or uv run pytest, then deploy again. |