Thank you for volunteering to help test our early access release of Modular community packages!

This document outlines the process for submitting your package that uses Mojo and MAX to the Modular community channel. This guide is geared towards community members who would like to distribute their packages to the wider Modular community and beyond via Magic 🪄

If you have any questions, please ping Caroline (@caroline_frasca) on Discord or via email (caroline@modular.com). You can also join the new Modular forum and post questions and feedback on the package submitter topic.

Submit your package to the community channel

To submit your package to the Modular community channel, you’ll need to:

Fork the Modular community channel GitHub repository
Add a folder to the /recipes folder. Give it the same name as your package.
In the folder for your package, include a rattler-build recipe file named recipe.yaml.

What is `rattler-build`?

rattler-build is a tool for creating cross-platform, relocatable packages using a simple recipe format. rattler-build recipes enable developers to easily create a Conda package from an existing Mojo or Python project, which, in turn, means that the package can be installed with Magic. Want to learn more about rattler-build? Check out the GitHub repository, the documentation, and the blog post.

Create your `recipe.yaml` file

To create the recipe.yaml file for your project, you can start with the following template:

YAML

context: version: "0.0.1" package: name: "hue" version: ${{ version }} source: - git: https://github.com/thatstoasty/hue.git rev: 32ff979d86393cf91068ead70e96ce18cd701106 build: number: 3 script: - mojo package src/hue -o ${{ PREFIX }}/lib/mojo/hue.mojopkg requirements: host: - max run: - ${{ pin_compatible('max') }} tests: - script: - if: unix then: - mojo run test.mojo files: recipe: - test.mojo about: homepage: https://github.com/thatstoasty/hue # Remember to specify the license variants for BSD, Apache, GPL, and LGPL. # Use the SPDX identifier, e.g: GPL-2.0-only instead of GNU General Public License version 2.0 # See https://spdx.org/licenses/ license: MIT # It is strongly encouraged to include a license file in the package, # (even if the license doesn't require it) using the license_file entry. # See https://docs.conda.io/projects/conda-build/en/latest/resources/define-metadata.html#license-file license_file: LICENSE summary: A library for playing with colors in Mojo. repository: https://github.com/thatstoasty/hue extra: maintainers: - thatstoasty

As you’re updating the template for your own package, don’t forget to update the following fields:

context/version : the version of your package that is being distributed
package/name : the name of your package, which should correspond to the name of the GitHub repository
source/git : the URL of your package’s GitHub repository
source/rev : the ID/SHA/hash for the commit being distributed
build/number : this number should be zero when your package is submitted to the Modular community channel for the first time; this number should be incremented each time you submit an update for the same version, and should be zero when you submit a new version of the package
build/script : the script containing the logic that carries out the build steps for your package; this example is a Mojo package – for Python packages, check out the examples in Prefix.dev’s docs (for both Python-only packages and packages with compiled extensions).
test/script/then : the invocation for your tests
tests/files : the name(s) of the files, located in your package’s GitHub repo, containing your tests (note: you do not need to include your test files in your pull request; you can keep your tests in your package’s repo, as long as you provide the path to that file in the test invocation)
about/homepage : the homepage for your package; this is usually the GitHub repository, but if you have a separate website for your package, feel free to list it here
about/license : the license type (e.g. MIT)
about/license_file : the name of the license file in your package (normally LICENSE)
about/summary : a short description of what your package does
about/repository : the link to your project’s GitHub repository
extra/maintainers : your GitHub username, and the username(s) of any other maintainers for your package; you can include up to to 5 maintainers
extra/project_name : the human-readable name project name for your package (e.g. if the name of your project’s repo is example-package, project_name would be Example Package)

Add an image

We’d love to feature packages from the Modular community channel on the MAX Builds website (with attribution). You can help us feature your package by including your project’s logo file (named image.jpeg) in the project’s folder.

‍

If your project doesn’t have a logo, feel free to share a 5-20 character description of what you’d like your logo/image to look like (in the pull request description), and our team can put something together.

Make sure your package meets the security requirements

If your project uses Python or any programming languages other than Mojo, we ask that you enable CodeQL scanning on your package’s repository, and display a badge representing the repo’s CodeQL status in the repo’s README.

Enable CodeQL scanning by following these instructions.
Add the badge to your README by copying and pasting the following (and updating {username} and {repo}):

Markdown

![CodeQL](https://github.com/{username}/{repo name}/workflows/CodeQL/badge.svg)

Reviewing PR file structure

To sum up, your PR should add a folder with the same name as your project, that includes a recipe.yml file and an image.jpeg file (optional).

This structure should look like:

📦 project-name

┣ 📜 recipe.yaml

┣ 🖼️ image.jpeg

Share feedback

Once you’ve submitted your package, please share your feedback via this form.

You can also join the new Modular forum and post questions and feedback on the package submitter topic.

‍

How to submit a package to MAX Builds