src/doc/rustc/src/platform-support/armv7-sony-vita-eabihf.md

   1 # armv7-sony-vita-eabihf
   2
   3 **Tier: 3**
   4
   5 This tier supports the ARM Cortex A9 processor running on a PlayStation Vita console. `armv7-vita-newlibeabihf` aims to have support for `std` crate using `newlib` as a bridge.
   6
   7 ## Designated Developers
   8
   9 * [@amg98](https://github.com/amg98)
  10
  11 ## Requirements
  12
  13 This target is cross compiled, and requires installing [VITASDK](https://vitasdk.org/) toolchain on your system.
  14
  15 ## Building
  16
  17 You can build Rust with support for the target by adding it to the `target`
  18 list in `config.toml`:
  19
  20 ```toml
  21 [build]
  22 build-stage = 1
  23 target = ["armv7-sony-vita-newlibeabihf"]
  24 ```
  25
  26 ## Cross-compilation
  27
  28 This target can be cross-compiled from `x86_64` on either Windows, MacOS or Linux systems. Other hosts are not supported for cross-compilation.
  29
  30 ## Testing
  31
  32 Currently there is no support to run the rustc test suite for this target.
  33
  34 ## Building and Running Rust Programs
  35
  36 To test your developed rust programs for PlayStation Vita, first you have to prepare a proper executable for the device using the resulting ELF file you get from compilation step. The needed steps can be automated using tools like `cargo-make`. Use the example below as a template for your project:
  37
  38 ```toml
  39 [env]
  40 TITLE = "Rust Hello World"
  41 TITLEID = "RUST00001"
  42 # At least a "sce_sys" folder should be place there for app metadata (title, icons, description...)
  43 # You can find sample assets for that on $VITASDK/share/gcc-arm-vita-eabi/samples/hello_world/sce_sys/
  44 STATIC_DIR = "static"   # Folder where static assets should be placed (sce_sys folder is at $STATIC_DIR/sce_sys)
  45 CARGO_TARGET_DIR = { script = ["echo ${CARGO_TARGET_DIR:=target}"] }
  46 RUST_TARGET_PATH = { script = ["echo $(pwd)"]}
  47 RUST_TARGET = "armv7-sony-vita-newlibeabihf"
  48 CARGO_OUT_DIR = "${CARGO_TARGET_DIR}/${RUST_TARGET}/release"
  49
  50 [tasks.xbuild]
  51 # This is the command where you get the ELF executable file (e.g. call to cargo build)
  52
  53 [tasks.strip]
  54 description = "Strip the produced ELF executable."
  55 dependencies = ["xbuild"]
  56 command = "arm-vita-eabi-strip"
  57 args = ["-g", '${CARGO_OUT_DIR}/${CARGO_MAKE_CRATE_FS_NAME}.elf']
  58
  59 [tasks.velf]
  60 description = "Build an VELF executable from the obtained ELF file."
  61 dependencies = ["strip"]
  62 command = "vita-elf-create"
  63 args = ['${CARGO_OUT_DIR}/${CARGO_MAKE_CRATE_NAME}.elf', '${CARGO_OUT_DIR}/${CARGO_MAKE_CRATE_NAME}.velf']
  64
  65 [tasks.eboot-bin]
  66 description = "Build an `eboot.bin` file from the obtained VELF file."
  67 dependencies = ["velf"]
  68 command = "vita-make-fself"
  69 args = ["-s", '${CARGO_OUT_DIR}/${CARGO_MAKE_CRATE_NAME}.velf', '${CARGO_OUT_DIR}/eboot.bin']
  70
  71 [tasks.param-sfo]
  72 description = "Build the `param.sfo` manifest using with given TITLE and TITLEID."
  73 command = "vita-mksfoex"
  74 args = ["-s", 'TITLE_ID=${TITLEID}', '${TITLE}', '${CARGO_OUT_DIR}/param.sfo']
  75
  76 [tasks.manifest]
  77 description = "List all static resources into a manifest file."
  78 script = [
  79   'mkdir -p "${CARGO_OUT_DIR}"',
  80   '''
  81   if [ -d "${STATIC_DIR}" ]; then
  82     find "${STATIC_DIR}" -type f > "${CARGO_OUT_DIR}/MANIFEST"
  83   else
  84     touch "${CARGO_OUT_DIR}/MANIFEST"
  85   fi
  86   '''
  87 ]
  88
  89 [tasks.vpk]
  90 description = "Build a VPK distribution of the project executable and resources."
  91 dependencies = ["eboot-bin", "param-sfo", "manifest"]
  92 script_runner = "@rust"
  93 script = [
  94     '''
  95     use std::io::BufRead;
  96     use std::fs::File;
  97
  98     fn main() {
  99
 100       let crate_name = env!("CARGO_MAKE_CRATE_NAME");
 101       let static_dir = env!("STATIC_DIR");
 102       let out_dir = std::path::PathBuf::from(env!("CARGO_OUT_DIR"));
 103
 104       let mut cmd = ::std::process::Command::new("vita-pack-vpk");
 105       cmd.arg("-s").arg(out_dir.join("param.sfo"));
 106       cmd.arg("-b").arg(out_dir.join("eboot.bin"));
 107
 108       // Add files from MANIFEST
 109       if let Ok(file) = File::open(out_dir.join("MANIFEST")) {
 110           let mut reader = ::std::io::BufReader::new(file);
 111           let mut lines = reader.lines();
 112           while let Some(Ok(line)) = lines.next() {
 113               let p1 = ::std::path::PathBuf::from(line);            // path on FS
 114               let p2 = p1.strip_prefix(static_dir).unwrap();        // path in VPK
 115               cmd.arg("--add").arg(format!("{}={}", p1.display(), p2.display()));
 116           }
 117       }
 118
 119       cmd.arg(out_dir.join(format!("{}.vpk", crate_name)))
 120         .output()
 121         .expect("command failed.");
 122     }
 123     '''
 124 ]
 125 ```
 126
 127 After running the above script, you should be able to get a *.vpk file in the same folder your *.elf executable resides. Now you can pick it and install it on your own PlayStation Vita using, for example, [VitaShell](https://github.com/TheOfficialFloW/VitaShell/releases) or you can use an emulator. For the time being, the most mature emulator for PlayStation Vita is [Vita3K](https://vita3k.org/), although I personally recommend testing your programs in real hardware, as the emulator is quite experimental.