Engines

Perseus' plugins system aims to enable extreme extensibility of Perseus to support niche use-cases, but it can't do everything. Occasionally, a problem is best solved by rewriting significant parts of the contents of .perseus/. These contents constitute Perseus' engine, the thing that ties together all the code exposed by the various Perseus libraries into an app. As mentioned before, the engine actually takes in your app's code as a library and produces a final app based on it (so technically, the engine is your app in the strictest sense, you provide the details).

The Perseus CLI comes bundled with the default Perseus engine, but, be it for experimentation of necessary workarounds, it also supports using custom engines by providing the -e option at the top level (that is, perseus -e <engine> serve or similar). The value of this should be a URL to a Git repository available online, and a branch name can be optionally supplied after an @ at the end (e.g. https://github.com/user/repo@v3.0.1). The URL provided should be one that can be put into the git clone command, and the branch (if provided) must be available on the repository. If you're routinely using an alternative engine, it's best for convenience to alias the perseus command to perseus -e <custom-engine-url> on your system.

Note that if a custom branch is not supplied, the CLI will fetch from the stable branch by default, which MUST correspond to the latest stable version of the engine.

Developing Engines

Developing a custom engine can be quite difficult, because Perseus expects a lot of things to be true. For starters, you'll need to follow a folder structure identical to the default Perseus engine (which you can find here). There are three modules here, the root one (responsible for exposing a library that wasm-pack will interpret as the app and exposing the user's app's code to the other modules), the server, and the builder (responsible for building and exporting).

The process of actually coding your engine should best start by copying the code of the default engine, and then tweaking it piece by piece. For convenience, you may wish to do this in the context of the entire Perseus repository (which provides internal tools optimized for using an engine that's being actively developed). Beyond this, documentation is best provided by the actual code itself. However, any problems you have can be raised on the Perseus Discord channel on Sycamore's server.

Working with the CLI

The CLI works with the binaries in builder in particular, and you should be careful to keep the same file structure as the default engine. Further, the CLI expects certain dependencies in certain places. Specifically, the root and builder crates are expected to import perseus, and the server crate is expected to import perseus and all of its integrations (though you don't need to use all of them). In the branch of your repository used by users to download from, you'll need to use the tokens PERSEUS_VERSION, PERSEUS_ACTIX_WEB_VERSION, and PERSEUS_WARP_VERSION to replace the versions of these packages in Cargo.toml files. The reason for this is that the CLI will replace them with the appropriate version directly (and relative paths to the packages will be used when working inside the Perseus repository).

Versioning

You may version your engine however you'd like to, though, for simplicity, it's generally recommended that you keep your engine on the same version number as the Perseus packages. The reason for this is because the CLI will impose its own version onto your engine (e.g. if you were using v0.2.2 but the user's copy of the CLI was at v0.3.1, the latter would be used). This means that your engine can break with changes in the CLI, hence why it's recommended to keep versions in lockstep.

Semantic Versioning

Perseus is strict with semantic versioning and not introducing breaking changes to end users, but the same policy does not apply to engines. Internal code used by engines and not end users could experience breaking changes at any time, which is why it's recommended to explicitly tell your users to stay on one version of Perseus until you've prepared for an upgrade. Note also that, as Perseus becomes more mature, these changes will become much less frequent.

Once Perseus reaches v1.0.0, the policy of introducing breaking changes without warning to code used only by engines will be reviewed.

A Final Note

Engines are suitable for extreme customizations of Perseus. As a general rule, if you can do it with a plugin, even if it's inconvenient, you should, because maintaining a custom engine will likely be very difficult!