Skip to content
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

docs: add cargo links #4

Merged
merged 2 commits into from
Oct 28, 2024
Merged

docs: add cargo links #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ff95df8
docs: add cargo links
blooop Oct 27, 2024
d5d122d
update pixi.lock
blooop Oct 28, 2024
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
89 changes: 10 additions & 79 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,89 +14,20 @@

## Intro

This a template for creating [rocker](https://github.com/tfoote/rocker) extensions. It used [off-your-rocker](https://github.com/sloretz/off-your-rocker) as a starting point, and migrated to use `pyproject.toml` instead of `setup.py` to help manage the development environment and continuous integration in a modern way using [pixi](https://pixi.sh). [Pixi](https://github.com/prefix-dev/pixi) is a cross-platform package manager based on the conda ecosystem. It provides a simple and performant way of reproducing a development environment and running user defined tasks and worflows. It more lightweight than docker, but does not provide the same level of isolation or generality.
This is a [rocker](https://github.com/tfoote/rocker) extension for adding [cargo](https://github.com/jesseduffield/cargo) to an existing docker image. Check out the [rocker](https://github.com/osrf/rocker) GitHub page for more details on how Rocker and its extensions work. In short, Rocker allows you to add custom capabilities to existing Docker containers.

This has basic setup for
## Installation

* pylint
* ruff
* black
* pytest
* git-lfs
* basic github actions ci
* pulling updates from this template
* codecov
* pypi upload
* dependabot

# Install

1. Use github to use this project as a template
2. Clone the project and run, `scripts/update_from_template.sh` and then run the `scripts/rename_project.sh` to rename the project.

If you are using pixi, look at the available tasks in pyproject.toml. If you are new to pixi follow the instructions on the pixi [website](https://prefix.dev/)

# Github setup

There are github workflows for CI, codecov and automated pypi publishing in `ci.yml` and `publish.yml`.

ci.yml uses pixi tasks to set up the environment matrix and run the various CI tasks. To set up codecov on github, you need to get a `CODECOV_TOKEN` and add it to your actions secrets.

publish.yml uses [pypy-auto-publish](https://github.com/marketplace/actions/python-auto-release-pypi-github) to automatically publish to pypi if the package version number changes. You need to add a `PYPI_API_TOKEN` to your github secrets to enable this.

If you use vscode to attach to your development container it makes it easier to set up specific extensions for each project that don't need to be installed globally.

# Development

There are currently two ways of running code. The preferred way is to use pixi to manage your environment and dependencies.

```bash
$ cd project

$ pixi run ci
$ pixi run arbitrary_task
```
pip install cargo-rocker
```

# Adding Functionality

1. Rename cargo_rocker/cargo_rocker.py and the class inside to something more appropriate. Use scripts/rename and pass in the new project name.
2. Update the extension entrypoint in `pyproject.toml`

`[project.entry-points."rocker.extensions"]`

`cargo_rocker = "cargo_rocker.cargo_rocker:CargoRocker"`


e.g.:
`lazygit = "lazygit_rocker.lazygit_rocker:LazygitExtension"`


3. Update the `get_name()` function in the extension class. e.g. Updating the name to `lazygit` would mean that it would be activated by passing --lazygit to rocker

4. Add/update the docker snippets in the templates folder. Officially the extension is supposed to be .Dockerfile.em to indicate it's passed to the empy library, but I have left them as .Dockerfile as I get Dockerfile highlighting out of the box that way.
5. Develop your extension. I find that using `pip install -e .` and running the extension with rocker on my host system is the easiest way to get started.

```bash
rocker --lazygit ubuntu:22.04

#check that everything works as expected
```



## Troubleshooting

The main pixi tasks are related to CI. Github actions runs the pixi task "ci". The CI is mostly likey to fail from a lockfile mismatch. Use `pixi run fix` to fix any lockfile related problems.

## vscode tasks

There are two core tasks.

1. set \<cfg\> from active file

This sets \<cfg\> to the currently opened file in the editor
## Usage

2. run \<cfg\>
To install cargo in an image use the `--cargo` flag

This runs python with the file set in \<cfg\>
```
#add cargo to the ubuntu:22.04 image
rocker --cargo ubuntu:22.04
```

4 changes: 2 additions & 2 deletions pixi.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
[project]
name = "cargo_rocker"
version = "0.0.2"
version = "0.0.3"
authors = [{ name = "Austin Gregg-Smith", email = "blooop@gmail.com" }]
description = "A rocker extension for installing pixi in a container"
description = "A rocker extension for installing cargo in a container"
readme = "README.md"
license = "MIT"

Expand Down