.. |gp4a| replace:: *GNAT Pro for Ada*

.. |gp4r| replace:: *GNAT Pro for Rust*

.. _Developing_Mixed_Language_Projects:

Developing Mixed Language Projects
**********************************

With a |gp4a| subscription, you can use the ``gprbuild`` tool in |gp4r| to create applications that combine Ada and Rust.
This chapter illustrates how to write a program with an Ada main procedure that invokes Rust functions from static and dynamic library crates.
Combining Ada and Rust involves using a C interface on the Ada side and the ``std::ffi`` or ``core::ffi`` (Foreign Function Interface) module in the Rust code.

This section is specific to native Linux and native Windows.
For instructions on building and running mixed language projects that execute on ``no_std`` targets or require cross-compilation, please see :ref:`Platform_Specific_Information`.

Current Limitations
===================

This version of |gp4r| covers only the use case of an Ada main with Rust libraries.
Future versions should offer complete mixed language support, including support for a Rust main with Ada libraries.

Ada Main with Rust Library
==========================

We will start by creating a Rust library and an Ada main, which will output the greetings ``Hello from Rust!`` and ``Hello from Ada!``, respectively.

The directory structure we are about to create is not mandatory for mixed language development.
It simply illustrates the division of the source code across languages.

In a directory of your choice, create the following directory structure:

.. only:: html or latex

  .. image:: developing_mixed_lang-ada_with_rust.png

.. only:: not (html or latex)

  .. code-block:: none

     ada_with_rust/
     +-- ada/
     +-- rust/

Rust Library
------------

Creating
~~~~~~~~

Navigate to directory :file:`ada_with_rust/rust` and execute:

  .. code-block:: bash

     $ cargo new --lib hello_from_rust

By default, the :command:`cargo new --lib` command will create a package for an ``rlib`` (Rust static library) that adds two numbers.

The command should create directory :file:`hello_from_rust` with the following contents:

.. only:: html or latex

  .. image:: developing_mixed_lang-hello_from_rust.png

.. only:: not (html or latex)

  .. code-block:: none

     hello_from_rust/
     +-- Cargo.toml
     +-- src/
         +-- lib.rs

* :file:`Cargo.toml` is the manifest file used by :command:`cargo`.

* :file:`src/lib.rs` contains the source code of the library.

However, an ``rlib`` is not suitable for mixed language development.
To convert the library into either a ``cdylib`` (native dynamic library) or a ``staticlib`` (native static library), edit file :file:`Cargo.toml` as follows:

  .. code-block:: toml

     [package]
     name = "hello_from_rust"
     version = "0.1.0"
     edition = "2021"

     [lib]
     crate-type = ["staticlib"]

     [dependencies]

The ``crate-type`` property indicates the package kind.
Consult `The Manifest Format <../_static/cargo/reference/manifest.html>`_ for further details.

Edit file :file:`src/lib.rs` as follows:

  .. code-block:: rust

     #[no_mangle]
     pub extern "C" fn hello_from_rust() {
         println!("Hello from Rust!");
     }

Functions that are intended for use by other languages through the C ABI must be subject to attribute ``#[no_mangle]`` and marked as ``extern "C"``.
Attribute ``#[no_mangle]`` causes the related item to be publicly exported from the produced library or object file.
ABI specification ``extern "C"`` indicates that the related item uses the C ABI.
Consult `Foreign Function Interface <../_static/nomicon/ffi.html>`_ for further details.

Building
~~~~~~~~

To build the Rust library, execute:

  .. code-block:: bash

     $ cargo build --release

The command should terminate successfully with output similar to the following:

  .. code-block:: none

     Compiling hello_from_rust v0.1.0 (<path/to/program>)
     Finished release [optimized] target(s) in <time>

Command line argument ``--release`` is mandatory for mixed-language development in this version of |gp4r|.

Ada Main
--------

Creating
~~~~~~~~

Navigate to directory :file:`ada_with_rust/ada`, and create file :file:`hello_from_rust.gpr` with the following content:

  .. code-block:: ada

     library project Hello_From_Rust is

        for Languages use ("Rust");
        for Library_Name use "hello_from_rust";
        for Library_Dir use Project'Project_Dir & "../rust/" & Project'Library_Name;
        for Source_Dirs use (Project'Library_Dir & "/src");
        for Externally_Built use "true";

        package Naming is
           for Body_Suffix ("Rust") use ".rs";
        end Naming;

     end Hello_From_Rust;

Each Rust library must have exactly one corresponding GPR project in this version of |gp4r|.

The Rust library project must be configured as follows:

* Attribute ``Library_Name`` must be the same as the name of the Rust package.
* Attribute ``Library_Dir`` must indicate the path to the Rust package, aka the *package root*.
* Attribute ``Source_Dirs`` must indicate the source directory within the package root.
* Attributes ``Languages`` and ``Externally_Built`` must be present, with the values shown above.

Create file :file:`hello_from_ada.gpr` with the following content:

  .. code-block:: ada

     with "hello_from_rust.gpr";

     project Hello_From_Ada is

        for Languages use ("Ada");
        for Object_Dir use "obj";
        for Exec_Dir use ".";

        for Main use ("hello_from_ada.adb");

        for Target use "<target>";

     end Hello_From_Ada;

  where ``<target>`` is ``x86_64-linux`` on native Linux and ``x86_64-windows64`` on native Windows.

The Ada main project must be configured as follows:

* The project must "with" each Rust library project.
* Attribute ``Target`` must indicate the compilation target.

Create file :file:`hello_from_ada.adb` with the following content:

  .. code-block:: ada

     with Ada.Text_IO; use Ada.Text_IO;

     procedure Hello_From_Ada is
        procedure Hello_From_Rust with Import, Convention => C;

     begin
        Put_Line ("Hello from Ada!");
        Hello_From_Rust;

     end Hello_From_Ada;

Building
~~~~~~~~

To build the Ada main for Linux, execute:

  .. code-block:: bash

     $ gprbuild -P hello_from_ada.gpr

When building for Windows, it is currently necessary to add a few linker flags;
future versions of |gp4r| will remove this need. With the current version of
the product, execute:

  .. code-block:: bash

     $ gprbuild -P hello_from_ada.gpr -largs -ladvapi32 -lbcrypt \
         -lgcc -lgcc_eh -lkernel32 -lmingw32 -lmingwex -lmsvcrt \
         -lntdll -luser32 -luserenv -lws2_32

The command should terminate successfully with output similar to the following:

  .. code-block:: none

     Setup
        [mkdir]        object directory for project Hello_From_Ada
     Compile
        [Ada]          hello_from_ada.adb
     Bind
        [gprbind]      hello_from_ada.bexch
        [Ada]          hello_from_ada.ali
     Link
        [link]         hello_from_ada.adb

Running
~~~~~~~

To run the Ada main, execute:

  .. code-block:: bash

     $ ./hello_from_ada

The command should terminate successfully with output similar to the following:

  .. code-block:: none

     Hello from Ada!
     Hello from Rust!