xbuild

The xbuild manifest parser follows the standard Cargo Cargo.toml structure, supporting both virtual workspaces and individual packages.

Key Components

• Workspace: A manifest that defines a collection of packages. It can contain members (paths to package directories) and default_members. A workspace can also define a package section (of type WorkspacePackage) to provide root-level values like version and description.
• Package: A standard Cargo package definition. It must contain a name. Fields like version and description use the Inheritable pattern.
• Inheritable Values: Certain fields in a Package can either be a direct value or marked for inheritance from the workspace. This is represented by the Inheritable<T> type.

Schema Summary

When using x build, certain platform-specific constraints apply:

Android

• Library Requirement: To build APKs or AABs, your project must contain a src/lib.rs file (it must be a library crate, not just a binary).
• AAB Limitation: Android App Bundles (AABs) can only be built using the android_gradle configuration. Direct packaging is not supported for AABs.

macOS

• Notarization: If a target API key is provided, xbuild will attempt to notarize the AppBundle or the resulting .dmg.
• DMG Creation: If the target format is Dmg, xbuild will create a disk image and can sign it if a signer is provided.

iOS

• Provisioning: You can provide a provisioning profile to be included in the AppBundle.
• Assets: Supports including Assets.car files via the configuration.

Windows

• Supported Formats: Currently supports Exe (simple binary copy) and Msix (packaged application). Other formats are unsupported.

The BuildEnv struct is the primary orchestrator for an xbuild session. It encapsulates the Cargo configuration, the BuildTarget requirements, and paths to SDKs and build directories.

Key Capabilities

• Path Resolution: Automatically calculates paths for build_dir, cache_dir, output, and executable based on the target.
• SDK Integration: Provides access to platform-specific SDK paths (e.g., android_sdk(), macos_sdk(), windows_sdk()).
• Cargo Orchestration: The cargo_build method prepares a CargoBuild instance configured with the correct linker arguments, RPATHs, and SDK paths for the target platform.
• Artifact Management: Use cargo_artefact to locate the resulting compiled files.

impl BuildEnv {
    pub fn new(args: BuildArgs) -> Result<Self>;
    pub fn cargo_build(&self, target: CompileTarget, target_dir: &Path) -> Result<CargoBuild>;
    pub fn output(&self) -> PathBuf;
    pub fn executable(&self) -> PathBuf;
}

The AppImage struct provides a programmatic interface to construct an AppImage bundle. The process involves initializing a new AppImage directory, populating it with required files (like .desktop entries, icons, and application binaries), and finally calling build to compress the directory into a squashfs image wrapped with the xbuild runtime.

Workflow:

1. Call AppImage::new(build_dir, name) to initialize the .AppDir structure.
2. Use add_desktop(), add_icon(), and add_file() to populate the bundle.
3. Call build(out_path, signer) to generate the final executable.

Requirements:

• The mksquashfs command must be installed on the host system to perform the compression step.

use std::path::Path;
use appimage::AppImage;

fn main() -> anyhow::Result<()> {
    let build_dir = Path::new("./build");
    let app_name = "my-app".to_string();
    let output_path = Path::new("./my-app.AppImage");

    // 1. Initialize
    let appimage = AppImage::new(build_dir, app_name.clone())?;

    // 2. Populate
    appimage.add_desktop()?;
    appimage.add_icon(Path::new("assets/icon.png"))?;
    appimage.add_file(Path::new("target/release/my-app"), Path::new("my-app"))?;
    appimage.add_apprun()?;

    // 3. Build
    appimage.build(output_path, None)?;

    Ok(())
}

The x build command automates the process of compiling Rust code for multiple platforms and packaging them into distributable formats (like APK, AppBundle, AppImage, MSIX, etc.).

Key behaviors:

• Artifact Fetching: Automatically fetches precompiled artifacts unless running in --offline mode.
• Rust Compilation: Invokes cargo to build binaries or libraries (cdylib) for the specified target architectures.
• Android Special Handling:
  • Android App Bundles (AABs) currently require the android_gradle flag to be set, as they must be built via gradle rather than direct packaging.
  • Android builds require a library (lib.rs must exist) to create APKs or AABs.
  • Automatically collects required shared libraries (including libc++_shared.so if needed) and bundles them into the package.
• Platform Packaging:
  • Linux: Creates AppImage by adding apprun, desktop files, icons, and the main binary/library.
  • macOS: Creates AppBundle (.app), handles signing, notarization (if an API key is provided), and can create .dmg files.
  • iOS: Creates AppBundle (.app) and packages it into an .ipa file, supporting provisioning profiles and Assets.car.
  • Windows: Supports .exe (copying the binary) and .msix (packaging with manifest and icon).
• Assets & Icons: Automatically includes icons and assets defined in the project configuration.