From 6ab0513ebeb18cead165164b7419f6058464fe2e Mon Sep 17 00:00:00 2001 From: bunnie Date: Wed, 2 Feb 2022 23:46:06 +0800 Subject: [PATCH] update documentation --- apps/README.md | 38 ++++++++++++++++++++++++++++++++++++++ apps/ball/README.md | 10 ++++------ apps/repl/README.md | 11 ++++------- 3 files changed, 46 insertions(+), 13 deletions(-) create mode 100644 apps/README.md diff --git a/apps/README.md b/apps/README.md new file mode 100644 index 000000000..cdcab0910 --- /dev/null +++ b/apps/README.md @@ -0,0 +1,38 @@ +# Xous Apps and the Manifest Format + +You can add apps to Xous by creating crates in this directory and adding them to the workspace. + +1. Create an app by adding its crate to this directory, perhaps by copying an existing template and giving it a new name. Don't forget to change the name of the app in the app's `newapp/Cargo.toml` file, as this is what the build system uses to refer to the app. +2. Register the crate in the Workspace by editing the root `../Cargo.toml` (one directory above this README), and adding the new app crate's path to the `default-members` and the `members` lists. +3. Add an entry to `manifest.json` in this file so the build system can fold it into the system menus. Format documented below. +4. Rebuild using `cargo xtask app-image [app1] [app2] [...]`, where the `appN` are the names of the app crates you want to have built into your burnable Xous image. +5. Burn your new `xous.img` file onto your device using either the [JTAG method or the USB method](https://github.com/betrusted-io/betrusted-wiki/wiki/Updating-Your-Device). + +As of Xous 0.9.6, the OS takes up about half the available RAM (8 out of 16 MiB) for code + data. For smooth operation of the PDDB and other resources, we suggest leaving about 4MiB of free space, so apps should try to stay within the range of 4MiB in size. + +Note that as of Xous 0.9.6, code is copied into RAM from FLASH, so a large portion of the RAM usage is actually the code. This may be addressed in future versions, but this would require a fairly major break with how code verification and updates are done. + +# manifest.json Format + +Each entry for an app needs a record in `manifest.json` with this format: + +```json + "app_crate_name": { + "context_name": "freeform name", + "menu_name": { + "appmenu.app_name": { + "en": "app name in english", + "ja": "app name in japanese", + "zh": "app name in chinese", + "en-audio": "app name for the blind" + } + } + }, +``` + +- All app names and descriptors must be unique across the build system +- `app_crate_name` should be replaced with the name of your app as specified by the "package" name in the app's `Cargo.toml` file. +- `context_name` is a reserved keyword and cannot be modified; its associated value ("freeform name" in this example) is a unique, free-from name that you give your app. There is a 64-character limit on this field. +- `menu_name` is a reserved keyword and cannot be modified. +- `appmenu.app_name` is the localization substitution string. This must be a unique name, and it s free-form. By convention, we use `appname.` as a prefix to the name of the app as described in the crate, but as long as it is unique nothing should break. +- Within the the `appmenu.app_name` record are the localized names for your App. We suggest creating strings for every language supported by the system. If you don't know how to translate your name, just use the same name in the language of your preference. This will at least prevent builds from breaking in different languages. diff --git a/apps/ball/README.md b/apps/ball/README.md index 28c029957..5ee73a17e 100644 --- a/apps/ball/README.md +++ b/apps/ball/README.md @@ -14,9 +14,7 @@ This is a fairly "raw iron" demo, and would be a reasonable starting point for s for example, wants to write a video game. ## Copying This App -1. Add a UX context by editing `services/gam/src/lib.rs/EXPECTED_BOOT_CONTEXTS` -2. Copy this demo application, and rename the relevant structures in its `Cargo.toml` and `main.rs`. -3. Add it to the Workspace `default-members` and `members` arrays by editing `./Cargo.toml` -4. Add it to the build by editing `xtask/src/main.rs` and inserting it into the relevant descriptor. Typically, you would insert your app into the `hw_pkgs` array, as this is what is built and targeted for full hardware builds. Most of the other trimmed-down descriptors are for debug, emulation, and benchmarking. -5. (optional) You may also need to run `cargo xtask generate-locales` if you modify/add any internationalization strings. -6. Add entries to the app switching menu. `services/status/src/appmenu.rs` to add the menu item (plus `locales/i18n.json` in the status directory if you want translated names for the app), and `services/status/src/main.rs` to add the Opcode (inside the `StatusOpcode` struct, around line 55) and the actual operation itself (in the main `loop`, around line 670). +1. Copy this demo application, and rename the relevant structures in its `Cargo.toml` and `main.rs`. +2. Add it to the Workspace `default-members` and `members` arrays by editing `./Cargo.toml` +3. Edit the `manifest.json` file as documented in its [README](../README.md) +4. Build using `cargo xtask app-image you_new_app` to create a flashable Xous image with your app in it. \ No newline at end of file diff --git a/apps/repl/README.md b/apps/repl/README.md index d8775c08d..fdc2d4007 100644 --- a/apps/repl/README.md +++ b/apps/repl/README.md @@ -3,13 +3,10 @@ A simple demo application that provides a bare-bones REPL framework. ## Copying This Demo to a New App -1. Add a UX context by editing `services/gam/src/lib.rs/EXPECTED_BOOT_CONTEXTS` -2. Copy this demo application, and rename the relevant structures in its `Cargo.toml` and `main.rs`. -3. Add it to the Workspace `default-members` and `members` arrays by editing `./Cargo.toml` -4. Add it to the build by editing `xtask/src/main.rs` and inserting it into the relevant descriptor. Typically, you would insert your app into the `hw_pkgs` array, as this is what is built and targeted for full hardware builds. Most of the other trimmed-down descriptors are for debug, emulation, and benchmarking. -5. (optional) You may also need to run `cargo xtask generate-locales` if you modify/add any internationalization strings. -6. Add entries to the app switching menu. `services/status/src/appmenu.rs` to add the menu item (plus `locales/i18n.json` in the status directory if you want translated names for the app), and `services/status/src/main.rs` to add the Opcode (inside the `StatusOpcode` struct, around line 55) and the actual operation itself (in the main `loop`, around line 670). - +1. Copy this demo application, and rename the relevant structures in its `Cargo.toml` and `main.rs`. +2. Add it to the Workspace `default-members` and `members` arrays by editing `./Cargo.toml` +3. Edit the `manifest.json` file as documented in its [README](../README.md) +4. Build using `cargo xtask app-image you_new_app` to create a flashable Xous image with your app in it. ## Details ![screenshot](repl_screenshot.png)