.. |gp4a| replace:: *GNAT Pro for Ada* .. |gp4bm| replace:: *GNAT Pro for Bare Metal* .. |gp4r| replace:: *GNAT Pro for Rust* .. _Platform_Specific_Information: Platform-Specific Information ***************************** This Appendix presents the platform-dependent instructions for using |gp4r| to build, run, and debug Rust programs. It assumes that :file:`{INSTALL_DIR}` is the directory in which the product has been installed. Native Linux and Native Windows =============================== Introduction ------------ Native Linux and native Windows are targets which come with the Rust Standard Library consisting of: .. toctree:: alloc <../_static/alloc/index.html#http://> core <../_static/core/index.html#http://> proc_macro <../_static/proc_macro/index.html#http://> std <../_static/std/index.html#http://> test <../_static/test/index.html#http://> .. only:: not html * ``alloc`` * ``core`` * ``proc_macro`` * ``std`` * ``test`` The targets are identified by the following triples: ==================== ============================ AdaCore triple Rust triple ==================== ============================ ``x86_64-linux`` ``x86_64-unknown-linux-gnu`` ``x86_64-windows64`` ``x86_64-pc-windows-gnu`` ==================== ============================ Limitations ----------- The |gp4r| products for native Linux and native Windows have no known limitations. Using GNAT Pro for Rust ----------------------- sudoku ~~~~~~ Overview ^^^^^^^^ We will use the ``sudoku`` example located in :file:`{INSTALL_DIR}/share/examples/rust/sudoku` to illustrate how to use |gp4r|. The example demonstrates development with the Rust Standard Library, in particular the organization of source code into modules, the implementation of comparison and formatting traits, the use of simple data structures, and more. The example has the following structure: .. only:: html or latex .. image:: platform_specific-sudoku.png .. only:: not (html or latex) .. code-block:: none sudoku/ +-- Cargo.lock +-- Cargo.toml +-- README.txt +-- boards | +-- easy.txt | +-- expert.txt | +-- extreme.txt | +-- hard.txt | +-- master.txt | +-- medium.txt +-- clean.sh +-- compile.sh +-- run.sh +-- src +-- board.rs +-- main.rs +-- rules.rs +-- solver.rs :file:`Cargo.toml` is the manifest file used by :command:`cargo`. The manifest format is quite powerful as it allows you to specify the identity of your crate, its dependencies, target-specific details, profiles, workspaces, and much more. Consult `The Manifest Format <../_static/cargo/reference/manifest.html>`_ for further details. Directory ``boards`` contains sample input boards. ``clean.sh``, ``compile.sh``, and ``run.sh`` are simple helper scripts which clean up the build environment, compile, and run the example, respectively. Directory :file:`src` contains the source code of the example, split into several modules. Building ^^^^^^^^ Execute the following command to build the example: .. code-block:: bash $ cargo build :command:`cargo` is the Rust package manager, the entry point of |gp4r|. It offers an extensive set of commands and configurations. Consult `Cargo Commands <../_static/cargo/commands/index.html>`_ and `Cargo Reference <../_static/cargo/reference/index.html>`_ for further details. Running ^^^^^^^ Execute the following command to run the example: .. code-block:: bash $ cargo run -- boards/ Debugging ^^^^^^^^^ Start :command:`rust-gdb` by executing: .. code-block:: bash $ rust-gdb --args target/debug/sudoku boards/ Place a breakpoint on ``solve_one``, run the program, and observe the value of parameter ``column`` at the breakpoint by executing: .. code-block:: none (gdb) break sudoku::solver::solve_one (gdb) run (gdb) print column Quit :command:`rust-gdb` by executing: .. code-block:: none (gdb) quit mouse-in-maze ~~~~~~~~~~~~~ Overview ^^^^^^^^ We will use the ``mouse-in-maze`` example located in :file:`{INSTALL_DIR}/share/examples/rust/mouse-in-maze` to illustrate how to use |gp4r| and |gp4a| for mixed language development. The example consists of an Ada main and a Rust library. The example has the following structure: .. only:: html or latex .. image:: platform_specific-mouse_in_maze.png .. only:: not (html or latex) .. code-block:: none mouse-in-maze/ +-- ada/ │ +-- ansi_terminal.ads │ +-- ansi_terminal.gpr │ +-- bounded_dynamic_arrays.adb │ +-- bounded_dynamic_arrays.ads │ +-- clean.sh │ +-- compile.sh │ +-- console.adb │ +-- console.ads │ +-- global_options.adb │ +-- global_options.ads │ +-- hci.adb │ +-- hci.ads │ +-- maze.adb │ +-- maze.ads │ +-- maze-factory.adb │ +-- maze-factory.ads │ +-- maze-io.adb │ +-- maze-io.ads │ +-- mouse.adb │ +-- mouse.gpr │ +-- pool_manager.adb │ +-- pool_manager.ads │ +-- run.sh │ +-- search_leads.adb │ +-- search_leads.ads │ +-- traversal.adb │ +-- traversal.ads │ +-- traversal-display.adb │ +-- traversal-display.ads │ +-- unbounded_sequential_stacks.adb │ +-- unbounded_sequential_stacks.ads +-- clean.sh +-- compile.sh +-- README.txt +-- run.sh +-- rust/ +-- ansi_terminal/ +-- Cargo.lock +-- Cargo.toml +-- clean.sh +-- compile.sh +-- src/ +-- lib.rs Directory ``ada`` contains the sources for the Ada main. File :file:`ada/ansi_terminal.gpr` is the GPR project for the Rust library. File :file:`ada/mouse.gpr` is the GPR project for the Ada main. Directory ``rust`` contains the sources for the Rust library. ``clean.sh``, ``compile.sh``, and ``run.sh`` are simple helper scripts which clean up the build environment, compile, and run the example, respectively. Building ^^^^^^^^ Navigate to directory :file:`{INSTALL_DIR}/share/examples/rust/mouse-in-maze/rust/ansi_terminal` and execute the following command to build the Rust library: .. code-block:: bash $ cargo build --release Navigate to directory :file:`{INSTALL_DIR}/share/examples/rust/mouse-in-maze/ada` and execute the following command to build the Ada main: .. code-block:: bash $ gprbuild -P mouse.gpr --target= where ```` is ``x86_64-linux`` for native Linux and ``x86_64-windows64`` for native Windows. Running ^^^^^^^ Execute the following command to run the example: .. code-block:: bash $ ./mouse -w 10 -h 10 AArch64 Bare Metal ================== Introduction ------------ *AArch64 Bare Metal* is a ``no_std`` target which comes with the following Rust libraries: .. toctree:: alloc <../_static/alloc/index.html#http://> core <../_static/core/index.html#http://> .. only:: not html * ``alloc`` * ``core`` The target is identified by the following triples: =============== ======================== AdaCore triple Rust triple =============== ======================== ``aarch64-elf`` ``aarch64-unknown-none`` =============== ======================== Limitations ----------- |gp4r| for AArch64 Bare Metal has no known limitations. Using GNAT Pro for Rust ----------------------- data_structures ~~~~~~~~~~~~~~~ Overview ^^^^^^^^ We will use the ``data_structures`` example located in :file:`{INSTALL_DIR}/share/examples/rust/data_structures` to illustrate how to use |gp4r|. This example demonstrates ``no_std`` development, in particular the use of FFI (Foreign Function Interface) to interface with C code, the definition of a global allocator in order to use heap-allocated data structures, and the handling of panics. The example has the following structure: .. only:: html or latex .. image:: platform_specific-data_structures.png .. only:: not (html or latex) .. code-block:: none data_structures/ +-- .cargo | +-- config.toml +-- Cargo.lock +-- Cargo.toml +-- clean.sh +-- compile.sh +-- README.txt +-- run.sh +-- src +-- main.rs :file:`.cargo/config.toml` is the configuration file used by :command:`cargo`. The configuration format allows you to set environment details, HTTP and network details, patch application specifics, define registries, and more. Consult `Configuration <../_static/cargo/reference/config.html>`_ for further details. :file:`Cargo.toml` is the manifest file used by :command:`cargo`. The manifest format is quite powerful as it allows you to specify the identity of your crate, its dependencies, target-specific details, profiles, workspaces, and much more. Consult `The Manifest Format <../_static/cargo/reference/manifest.html>`_ for further details. ``clean.sh``, ``compile.sh``, and ``run.sh`` are simple helper scripts which clean up the build environment, compile, and run the example, respectively. :file:`src/main.rs` contains the source code of the example. Prerequisites ^^^^^^^^^^^^^ The example is tailored for the ZynqMP BSP and GNATemulator, both distributed with |gp4bm|. You can also build the example with your own BSP and linker script, and run it within your own emulator or physical board. Configuration ^^^^^^^^^^^^^ Before building the example, you will need to provide the BSP and linker script details to :command:`cargo`. Edit file :file:`{INSTALL_DIR}/share/examples/rust/data_structures/.cargo/config.toml` and follow the instructions in the comments. Building ^^^^^^^^ Execute the following command to build the example: .. code-block:: bash $ cargo build --target=aarch64-unknown-none :command:`cargo` is the Rust package manager, the entry point of |gp4r|. It offers an extensive set of commands and configurations. Consult `Cargo Commands <../_static/cargo/commands/index.html>`_ and `Cargo Reference <../_static/cargo/reference/index.html>`_ for further details. Running ^^^^^^^ Assuming you are using ZynqMP BSP and GNATemulator, execute the following command to run the example: .. code-block:: bash $ aarch64-elf-gnatemu target/aarch64-unknown-none/debug/data_structures Debugging ^^^^^^^^^ Debugging the example requires two terminals which we will refer to as *client* and *server* terminals. In the *server* terminal, run the example by executing: .. code-block:: bash $ aarch64-elf-gnatemu -g target/aarch64-unknown-none/debug/data_structures In the *client* terminal, register ``aarch64-elf-gdb`` with ``rust-gdb`` by executing: .. code-block:: bash $ export RUST_GDB=aarch64-elf-gdb :command:`rust-gdb` is a wrapper around :command:`gdb` which ensures proper path resolution and substitution within the debugger. Start :command:`rust-gdb` by executing: .. code-block:: bash $ rust-gdb target/aarch64-unknown-none/debug/data_structures Connect to the example running in the *server* terminal by executing: .. code-block:: none (gdb) target remote localhost:1234 Place a breakpoint on :file:`main.rs`, continue, and print the value of variable ``words`` by executing: .. code-block:: none (gdb) break main.rs:70 (gdb) continue (gdb) print words Quit :command:`rust-gdb` by executing: .. code-block:: none (gdb) quit arithmetic ~~~~~~~~~~ Overview ^^^^^^^^ We will use the ``arithmetic`` example located in :file:`{INSTALL_DIR}/share/examples/rust/arithmetic` to illustrate how to use |gp4r| and |gp4a| for mixed language development. The example consists of an Ada main and a Rust library. The example has the following structure: .. only:: html or latex .. image:: platform_specific-arithmetic.png .. only:: not (html or latex) .. code-block:: none arithmetic/ +-- ada | +-- arithmetic.adb | +-- arithmetic.gpr | +-- clean.sh | +-- compile.sh | +-- operations.gpr | +-- run.sh +-- clean.sh +-- compile.sh +-- README.txt +-- run.sh +-- rust +-- operations +-- .cargo | +-- config.toml +-- Cargo.lock +-- Cargo.toml +-- clean.sh +-- compile.sh +-- src +-- lib.rs Directory ``ada`` contains the sources for the Ada main. File :file:`ada/operations.gpr` is the GPR project for the Rust library. File :file:`ada/arithmetic.gpr` is the GPR project for the Ada main. Directory ``rust`` contains the sources for the Rust library. ``clean.sh``, ``compile.sh``, and ``run.sh`` are simple helper scripts which clean up the build environment, compile, and run the example, respectively. Prerequisites ^^^^^^^^^^^^^ The example is tailored for the ZynqMP BSP and GNATemulator, both distributed with |gp4bm|. You can also build the example with your own BSP and linker script, and run it within your own emulator or physical board. Configuration ^^^^^^^^^^^^^ Before building the example, you will need to provide the BSP and linker script details to :command:`cargo`. Edit file :file:`{INSTALL_DIR}/share/examples/rust/arithmetic/rust/operations/.cargo/config.toml` and follow the instructions in the comments. In addition, you will need to specify the Ada runtime to use. Edit file :file:`{INSTALL_DIR}/share/examples/rust/arithmetic/ada/arithmetic.gpr` and substitute ```` with ``light-zynqmp`` for example. Building ^^^^^^^^ Navigate to directory :file:`{INSTALL_DIR}/share/examples/rust/arithmetic/rust/operations` and execute the following command to build the Rust library: .. code-block:: bash $ cargo build --release --target=aarch64-unknown-none Navigate to directory :file:`{INSTALL_DIR}/share/examples/rust/arithmetic/ada` and execute the following command to build the Ada main: .. code-block:: bash $ gprbuild -P arithmetic.gpr Running ^^^^^^^ Assuming you are using ZynqMP BSP and GNATemulator, execute the following command to run the example: .. code-block:: bash $ aarch64-elf-gnatemu arithmetic AArch64 FastOS ============== Introduction ------------ AArch64 FastOS is a target which comes with the Rust Standard Library consisting of: .. toctree:: alloc <../_static/alloc/index.html#http://> core <../_static/core/index.html#http://> proc_macro <../_static/proc_macro/index.html#http://> std <../_static/std/index.html#http://> test <../_static/test/index.html#http://> .. only:: not html * ``alloc`` * ``core`` * ``proc_macro`` * ``std`` * ``test`` The target is identified by the following triples: ================== ========================= AdaCore triple Rust triple ================== ========================= ``aarch64-fastos`` ``aarch64-thales-fastos`` ================== ========================= Limitations ----------- |gp4r| for AArch64 FastOS has the following limitations: Missing Features ~~~~~~~~~~~~~~~~ The following features are either not present in |gp4r| for AArch64 FastOS, or employ a non-functional implementation which panics or returns an error. File System ^^^^^^^^^^^ Ownership =================== ================================ Feature Comment =================== ================================ ``std::fs::fchown`` No ``fchown`` in FastOS ``libc`` ``std::fs::lchown`` No ``lchown`` in FastOS ``libc`` =================== ================================ Paths ========================= ================================== Feature Comment ========================= ================================== ``std::fs::canonicalize`` No ``realpath`` in FastOS ``libc`` ``std::fs::chroot`` No ``chroot`` in FastOS ``libc`` ========================= ================================== Symbolic links ================================= ============================ Feature Comment ================================= ============================ ``std::fs::FileType::is_symlink`` No symlink support on FastOS ``std::fs::read_link`` No symlink support on FastOS ``std::fs::soft_link`` No symlink support on FastOS ================================= ============================ Synchronization ============================ =================================== Feature Comment ============================ =================================== ``std::fs::File::sync_all`` No ``fsync`` in FastOS ``libc`` ``std::fs::FIle::sync_data`` No ``fdatasync`` in FastOS ``libc`` ============================ =================================== Timestamps ============================ ================================== Feature Comment ============================ ================================== ``std::fs::File::set_times`` No ``futimens`` in FastOS ``libc`` ============================ ================================== Vectored IO ==================================== ================================= Feature Comment ==================================== ================================= ``std::fs::File::read_at`` No ``pread`` in FastOS ``libc`` ``std::fs::File::read_vectored_at`` No ``preadv`` in FastOS ``libc`` ``std::fs::File::write_at`` No ``pwrite`` in FastOS ``libc`` ``std::fs::File::write_vectored_at`` No ``pwritev`` in FastOS ``libc`` ==================================== ================================= Networking ^^^^^^^^^^ Host lookup ======================================== ===================================== Feature Comment ======================================== ===================================== ``std::net::socket_addr::ToSocketAddrs`` No ``getaddrinfo`` in FastOS ``libc`` ======================================== ===================================== IPv6 FastOS lacks support for IPv6. The data structures which represent an IPv6 address are present in the Rust Standard Library since they do not depend on FastOS ``libc``. Socket options =============================================== ===================================== Feature Comment =============================================== ===================================== ``std::net::tcp::TcpStream::linger`` No ``SO_LINGER`` in FastOS ``libc`` ``std::net::tcp::TcpStream::read_timeout`` No ``SO_RCVTIMEO`` in FastOS ``libc`` ``std::net::tcp::TcpStream::set_linger`` No ``SO_LINGER`` in FastOS ``libc`` ``std::net::tcp::TcpStream::set_read_timeout`` No ``SO_RCVTIMEO`` in FastOS ``libc`` ``std::net::tcp::TcpStream::set_write_timeout`` No ``SO_SNDTIMEO`` in FastOS ``libc`` ``std::net::tcp::TcpStream::write_timeout`` No ``SO_SNDTIMEO`` in FastOS ``libc`` ``std::net::udp::UdpSocket::read_timeout`` No ``SO_RCVTIMEO`` in FastOS ``libc`` ``std::net::udp::UdpSocket::set_read_timeout`` No ``SO_RCVTIMEO`` in FastOS ``libc`` ``std::net::udp::UdpSocket::set_write_timeout`` No ``SO_SNDTIMEO`` in FastOS ``libc`` ``std::net::udp::UdpSocket::write_timeout`` No ``SO_SNDTIMEO`` in FastOS ``libc`` =============================================== ===================================== UNIX sockets ========================= ========================= Feature Comment ========================= ========================= ``std::os::unix::net::*`` No UNIX sockets on FastOS ========================= ========================= Processes ^^^^^^^^^ Exit codes ====================================================== ================================================== Feature Comment ====================================================== ================================================== ``std::os::unix::process::ExitStatus::continued`` No ``WIFCONTINUED`` in FastOS ``libc`` ``std::os::unix::process::ExitStatus::core_dumped`` No ``WCOREDUMP`` in FastOS ``libc`` ``std::os::unix::process::ExitStatus::stopped_signal`` No ``WIFSTOPPED``, ``WTSOPSIG`` in FastOS ``libc`` ====================================================== ================================================== Known Issues ~~~~~~~~~~~~ * The path returned by ``std::env::current_exe`` may be relative, depending on the value of ``argv[0]``. * ``std::f32::gamma`` and ``std::f64::gamma`` return ``+INF`` instead of ``-INF`` for ``-0.0``. * Using ``std::fs::File::set_len`` to truncate a file to a smaller length, then writing to the file without changing the cursor will not fill the intermediate characters with zeroes. * ``std::net::UdpSocket::peer_addr`` returns the ``0.0.0.0`` address instead of ``std::io::ErrorKind::NotConnected`` if no peer is connected to the socket. * ``std::process::Command::spawn`` does not function properly. * Building shared libraries is not supported. * Backtraces are not symbolized when unwinding during a panic. * Missing stack overflow handler. Using GNAT Pro for Rust ----------------------- sudoku ~~~~~~ Overview ^^^^^^^^ We will use the ``sudoku`` example located in :file:`{INSTALL_DIR}/share/examples/rust/sudoku` to illustrate how to use |gp4r|. The example demonstrates development with the Rust Standard Library, in particular organization of source code into modules, implementation of comparison and formatting traits, use of simple data structures, and more. The example has the following structure: .. only:: html or latex .. image:: platform_specific-sudoku.png .. only:: not (html or latex) .. code-block:: none sudoku/ +-- Cargo.lock +-- Cargo.toml +-- README.txt +-- boards | +-- easy.txt | +-- expert.txt | +-- extreme.txt | +-- hard.txt | +-- master.txt | +-- medium.txt +-- clean.sh +-- compile.sh +-- run.sh +-- src +-- board.rs +-- main.rs +-- rules.rs +-- solver.rs :file:`Cargo.toml` is the manifest file used by :command:`cargo`. The manifest format is quite powerful as it allows you to specify the identity of your crate, its dependencies, target-specific details, profiles, workspaces, and much more. Consult `The Manifest Format <../_static/cargo/reference/manifest.html>`_ for further details. Directory :file:`boards` contains sample input boards. ``clean.sh``, ``compile.sh``, and ``run.sh`` are simple helper scripts which clean up the build environment, compile, and run the example, respectively. Directory :file:`src` contains the source code of the example, split into several modules. Prerequisites ^^^^^^^^^^^^^ Ensure that the AArch64 FastOS kernel installed, and that ``ENV_PREFIX`` points to the directory which contains it. Building ^^^^^^^^ Execute the following command to build the example: .. code-block:: bash $ cargo build --target=aarch64-thales-fastos :command:`cargo` is the Rust package manager, the entry point of |gp4r|. It offers an extensive set of commands and configurations. Consult `Cargo Commands <../_static/cargo/commands/index.html>`_ and `Cargo Reference <../_static/cargo/reference/index.html>`_ for further details. Running ^^^^^^^ Assuming you are using a physical board, first copy the executable from :file:`{INSTALL_DIR}/share/examples/rust/sudoku/target/aarch64-thales-fastos/debug/sudoku` to your board. In addition, copy a few sudoku boards from directory :file:`boards` to your board. Execute the following command to run the example: .. code-block:: bash $ ./sudoku Debugging ^^^^^^^^^ Debugging the example requires two terminals which we will refer to as *client* and *server* terminals. Assuming you are using a physical board which is already provisioned with a gdb server, start the *server* terminal on the physical board. In the *server* terminal, run the example by executing: .. code-block:: bash $ :1234 --args sudoku where ``gdb-server`` is your gdb server executable. In the *client* terminal, register :command:`aarch64-thales-fastos-gdb` with :command:`rust-gdb` by executing: .. code-block:: bash $ export RUST_GDB=aarch64-thales-fastos-gdb :command:`rust-gdb` is a wrapper around :command:`gdb` which ensures proper path resolution and substitution within the debugger. Start :command:`rust-gdb` by executing: .. code-block:: bash $ rust-gdb target/aarch64-thales-fastos/debug/sudoku Connect to the example running in the *server* terminal by executing: .. code-block:: none (gdb) target remote :1234 Place a breakpoint on ``solve_one``, continue, and observe the value of parameter ``column`` by executing: .. code-block:: none (gdb) break sudoku::solver::solve_one (gdb) continue (gdb) print column Quit :command:`rust-gdb` by executing: .. code-block:: none (gdb) quit mouse-in-maze ~~~~~~~~~~~~~ Overview ^^^^^^^^ We will use the ``mouse-in-maze`` example located in :file:`{INSTALL_DIR}/share/examples/rust/mouse-in-maze` to illustrate how to use |gp4r| and |gp4a| for mixed language development. The example consists of an Ada main and a Rust library. The example has the following structure: .. only:: html or latex .. image:: platform_specific-mouse_in_maze.png .. only:: not (html or latex) .. code-block:: none mouse-in-maze/ +-- ada │ +-- ansi_terminal.ads │ +-- ansi_terminal.gpr │ +-- bounded_dynamic_arrays.adb │ +-- bounded_dynamic_arrays.ads │ +-- clean.sh │ +-- compile.sh │ +-- console.adb │ +-- console.ads │ +-- global_options.adb │ +-- global_options.ads │ +-- hci.adb │ +-- hci.ads │ +-- maze.adb │ +-- maze.ads │ +-- maze-factory.adb │ +-- maze-factory.ads │ +-- maze-io.adb │ +-- maze-io.ads │ +-- mouse.adb │ +-- mouse.gpr │ +-- pool_manager.adb │ +-- pool_manager.ads │ +-- run.sh │ +-- search_leads.adb │ +-- search_leads.ads │ +-- traversal.adb │ +-- traversal.ads │ +-- traversal-display.adb │ +-- traversal-display.ads │ +-- unbounded_sequential_stacks.adb │ +-- unbounded_sequential_stacks.ads +-- clean.sh +-- compile.sh +-- README.txt +-- run.sh +-- rust +-- ansi_terminal +-- Cargo.lock +-- Cargo.toml +-- clean.sh +-- compile.sh +-- src +-- lib.rs Directory ``ada`` contains the sources for the Ada main. File :file:`ada/ansi_terminal.gpr` is the GPR project for the Rust library. File :file:`ada/mouse.gpr` is the GPR project for the Ada main. Directory ``rust`` contains the sources for the Rust library. ``clean.sh``, ``compile.sh``, and ``run.sh`` are simple helper scripts which clean up the build environment, compile, and run the example, respectively. Prerequisites ^^^^^^^^^^^^^ Ensure that the AArch64 FastOS kernel installed, and that ``ENV_PREFIX`` points to the directory which contains it. Configuration ^^^^^^^^^^^^^ Before building the example, edit file :file:`{INSTALL_DIR}/share/examples/rust/mouse-in-maze/ada/mouse.gpr` and change ``x86_64-linux`` to ``aarch64-fastos``. Building ^^^^^^^^ Navigate to directory :file:`{INSTALL_DIR}/share/examples/rust/mouse-in-maze/rust/ansi_terminal` and execute the following command to build the Rust library: .. code-block:: bash $ cargo build --release --target=aarch64-thales-fastos Navigate to directory :file:`{INSTALL_DIR}/share/examples/rust/mouse-in-maze/ada` and execute the following command to build the Ada main: .. code-block:: bash $ gprbuild -P mouse.gpr Running ^^^^^^^ Assuming you are using a physical board, first copy the executable from directory :file:`{INSTALL_DIR}/share/examples/rust/mouse-in-maze/ada` to your board. Execute the following command to run the example: .. code-block:: bash $ ./mouse -w 10 -h 10 AArch64 Linux ============= Introduction ------------ AArch64 Linux is a target which comes with the Rust Standard Library consisting of: .. toctree:: alloc <../_static/alloc/index.html#http://> core <../_static/core/index.html#http://> proc_macro <../_static/proc_macro/index.html#http://> std <../_static/std/index.html#http://> test <../_static/test/index.html#http://> .. only:: not html * ``alloc`` * ``core`` * ``proc_macro`` * ``std`` * ``test`` The target is identified by the following triples: ================= ============================= AdaCore triple Rust triple ================= ============================= ``aarch64-linux`` ``aarch64-unknown-linux-gnu`` ================= ============================= Limitations ----------- |gp4r| for AArch64 Linux has no known limitations. Using GNAT Pro for Rust ----------------------- sudoku ~~~~~~ Overview ^^^^^^^^ We will use the ``sudoku`` example located in :file:`{INSTALL_DIR}/share/examples/rust/sudoku` to illustrate how to use |gp4r|. The example demonstrates development with the Rust Standard Library, in particular organization of source code into modules, implementation of comparison and formatting traits, use of simple data structures, and more. The example has the following structure: .. only:: html or latex .. image:: platform_specific-sudoku.png .. only:: not (html or latex) .. code-block:: none sudoku/ +-- Cargo.lock +-- Cargo.toml +-- README.txt +-- boards | +-- easy.txt | +-- expert.txt | +-- extreme.txt | +-- hard.txt | +-- master.txt | +-- medium.txt +-- clean.sh +-- compile.sh +-- run.sh +-- src +-- board.rs +-- main.rs +-- rules.rs +-- solver.rs :file:`Cargo.toml` is the manifest file used by :command:`cargo`. The manifest format is quite powerful as it allows you to specify the identity of your crate, its dependencies, target-specific details, profiles, workspaces, and much more. Consult `The Manifest Format <../_static/cargo/reference/manifest.html>`_ for further details. Directory :file:`boards` contains sample input boards. ``clean.sh``, ``compile.sh``, and ``run.sh`` are simple helper scripts which clean up the build environment, compile, and run the example, respectively. Directory :file:`src` contains the source code of the example, split into several modules. Prerequisites ^^^^^^^^^^^^^ Ensure that the AArch64 Linux system libraries are installed, and that ``ENV_PREFIX`` points to the directory which contains them. Building ^^^^^^^^ Execute the following command to build the example: .. code-block:: bash $ cargo build --target=aarch64-unknown-linux-gnu :command:`cargo` is the Rust package manager, the entry point of |gp4r|. It offers an extensive set of commands and configurations. Consult `Cargo Commands <../_static/cargo/commands/index.html>`_ and `Cargo Reference <../_static/cargo/reference/index.html>`_ for further details. Running ^^^^^^^ Assuming you are using a physical board, first copy the executable from :file:`{INSTALL_DIR}/share/examples/rust/sudoku/target/aarch64-unknown-linux-gnu/debug/sudoku` to your board. In addition, copy a few sudoku boards from directory :file:`boards` to your board. Execute the following command to run the example: .. code-block:: bash $ ./sudoku Debugging ^^^^^^^^^ Debugging the example requires two terminals which we will refer to as *client* and *server* terminals. Assuming you are using a physical board, first copy :file:`{INSTALL_DIR}/bin/aarch64-linux-gnu-gdbserver` to your board. Start the *server* terminal on the physical board. In the *server* terminal, run the example by executing: .. code-block:: bash $ aarch64-linux-gnu-gdbserver :1234 --args sudoku In the *client* terminal, register :command:`aarch64-linux-gnu-gdb` with :command:`rust-gdb` by executing: .. code-block:: bash $ export RUST_GDB=aarch64-linux-gnu-gdb :command:`rust-gdb` is a wrapper around :command:`gdb` which ensures proper path resolution and substitution within the debugger. Start :command:`rust-gdb` by executing: .. code-block:: bash $ rust-gdb target/aarch64-unknown-linux-gnu/debug/sudoku Connect to the example running in the *server* terminal by executing: .. code-block:: none (gdb) target remote :1234 Place a breakpoint on ``solve_one``, continue, and observe the value of parameter ``column`` by executing: .. code-block:: none (gdb) break sudoku::solver::solve_one (gdb) continue (gdb) print column Quit :command:`rust-gdb` by executing: .. code-block:: none (gdb) quit mouse-in-maze ~~~~~~~~~~~~~ Overview ^^^^^^^^ We will use the ``mouse-in-maze`` example located in :file:`{INSTALL_DIR}/share/examples/rust/mouse-in-maze` to illustrate how to use |gp4r| and |gp4a| for mixed language development. The example consists of an Ada main and a Rust library. The example has the following structure: .. only:: html or latex .. image:: platform_specific-mouse_in_maze.png .. only:: not (html or latex) .. code-block:: none mouse-in-maze/ +-- ada │ +-- ansi_terminal.ads │ +-- ansi_terminal.gpr │ +-- bounded_dynamic_arrays.adb │ +-- bounded_dynamic_arrays.ads │ +-- clean.sh │ +-- compile.sh │ +-- console.adb │ +-- console.ads │ +-- global_options.adb │ +-- global_options.ads │ +-- hci.adb │ +-- hci.ads │ +-- maze.adb │ +-- maze.ads │ +-- maze-factory.adb │ +-- maze-factory.ads │ +-- maze-io.adb │ +-- maze-io.ads │ +-- mouse.adb │ +-- mouse.gpr │ +-- pool_manager.adb │ +-- pool_manager.ads │ +-- run.sh │ +-- search_leads.adb │ +-- search_leads.ads │ +-- traversal.adb │ +-- traversal.ads │ +-- traversal-display.adb │ +-- traversal-display.ads │ +-- unbounded_sequential_stacks.adb │ +-- unbounded_sequential_stacks.ads +-- clean.sh +-- compile.sh +-- README.txt +-- run.sh +-- rust +-- ansi_terminal +-- Cargo.lock +-- Cargo.toml +-- clean.sh +-- compile.sh +-- src +-- lib.rs Directory ``ada`` contains the sources for the Ada main. File :file:`ada/ansi_terminal.gpr` is the GPR project for the Rust library. File :file:`ada/mouse.gpr` is the GPR project for the Ada main. Directory ``rust`` contains the sources for the Rust library. ``clean.sh``, ``compile.sh``, and ``run.sh`` are simple helper scripts which clean up the build environment, compile, and run the example, respectively. Prerequisites ^^^^^^^^^^^^^ Ensure that the AArch64 Linux system libraries are installed, and that ``ENV_PREFIX`` points to the directory which contains them. Building ^^^^^^^^ Navigate to directory :file:`{INSTALL_DIR}/share/examples/rust/mouse-in-maze/rust/ansi_terminal` and execute the following command to build the Rust library: .. code-block:: bash $ cargo build --release --target=aarch64-unknown-linux-gnu Navigate to directory :file:`{INSTALL_DIR}/share/examples/rust/mouse-in-maze/ada` and execute the following command to build the Ada main: .. code-block:: bash $ gprbuild -P mouse.gpr --target=aarch64-linux Running ^^^^^^^ Assuming you are using a physical board, first copy the executable from directory :file:`{INSTALL_DIR}/share/examples/rust/mouse-in-maze/ada` to your board. Execute the following command to run the example: .. code-block:: bash $ ./mouse -w 10 -h 10