Creating a Sample Rust Application¶

Use this procedure to create a sample Rust application as a foundation for learning how to create a binary package with eLxr.

About This Task¶

The application detailed in this procedure demonstrates the Fibonacci series, which takes the number of terms as a command-line parameter. You will create the minimum source files necessary for building the application and identifying how you plan to share it. For a Rust-based application, this includes the following files. These files are specific to the application itself, and required to build and test the application prior to packaging it.

A Cargo.toml file, generated automatically and updated as necessary for Rust application builds
Two source files, including a main.rs file to define application functionality and a fib_math.rs file that performs the numerical functions as a module.
A setup.py file that defines build requirements for Debian tools.
A Makefile to provide guidance for building the final binary and clean up the working directory
A LICENSE file

This example shows how to work with applications that are not yet part of your eLxr 12 image to help you understand the requirements for adding custom application packages. You can use this procedure for any stand-alone application that you want to develop and test apart from your eLxr image.

Note

A set of source files for the Rust fibonacci application is available at eLxr User Documentation: Samples repository. Simply create your folder structure and copy these files into your working directory to save yourself some time.

If you already have an application that you want to use, go to Modifying Package Template Files for Rust Applications to get your application ready for packaging.

Before You Begin¶

You must have a Linux development host or eLxr 12 image.
You must have the required development packages on your Linux development host or eLxr 12 image. For details, see Development Tools Overview and Requirements.
You must have the cargo package installed on your Linux development host, with the latest stable Rust release.

Procedure¶

Create a working directory for your application project.

$ mkdir -p ~/elxr-dev/fibonacci-rust-1.0
$ cd ~/elxr-dev/fibonacci-rust-1.0

Use cargo to create the fibonacci-rust-1.0 project.
```
$ cargo new fibonacci
```
Move the new project ro rename it. This is required due to the cargo limitation where hyphens (-) are not allowed, as they are assumed to be “invalid crate”.
```
$ mv fibonacci fibonacci-rust-1.0
```
Navigate to the fibonacci-rust-1.0 directory.
```
$ cd fibonacci-rust-1.0
```
Edit the Cargo.toml file to specify the application name in the [Package] section.
```
vi Cargo.toml
```
Update the application name and other content to match the following and save the file.
```
[package]
name = "fibonacci-rust"
version = "1.0.0"
edition = "2021"
```

Create the fibonacci-rust-1.0/main.rs file.

$ vi src/main.rs

Enter or copy the following text and save the file.

mod fib_math;

use std::env;

fn main() {
    let args: Vec<String> = env::args().collect();

    if args.len() != 2 {
        println!("Usage: {} <number_of_terms>", args[0]);
        return;
    }

    let count: u32 = args[1].parse().unwrap_or(0);

    for i in 0..count {
        println!("{}", fib_math::fibonacci(i));
    }
}

Create the fibonacci-rust-1.0/fib_math.rs file as a module.

$ vi src/fib_math.rs

Enter or copy the following text and save the file.

pub fn fibonacci(n: u32) -> u32 {
match n {
0 => 0,
1 => 1,
_ => fibonacci(n - 1) + fibonacci(n - 2),
        }
}

Create the fibonacci-rust-1.0/Makefile.

$ vi Makefile

Enter or copy the following text and save the file.

# This is public domain software

# Project metadata
NAME := fibonacci-rust
VERSION := 1.0
TARBALL := $(NAME)-$(VERSION).tar.gz
BUILD_DIR := target/release
BIN := $(BUILD_DIR)/$(NAME)
INSTALL_PATH := $(DESTDIR)/usr/local/bin/$(NAME)

# Default target
all: build

# Build the Rust project in release mode
build:
        cargo build --release

# Create source archive with metadata and source files
archive: $(TARBALL)

$(TARBALL): src/*.rs Cargo.toml LICENSE Makefile
        tar --transform 's,^,$(NAME)_$(VERSION)/,' -czvf $@ $^
        cp $@ ../

# Install the compiled binary to system path
install: build
        install -D $(BIN) $(INSTALL_PATH)

# Uninstall the binary from system path
uninstall:
        @echo "Removing installed binary from $(INSTALL_PATH)"
        rm -f $(INSTALL_PATH)

# Clean all build and generated files
clean:
        @echo "Cleaning build artifacts and generated files..."
        cargo clean
        rm -f $(TARBALL)
        rm -f *~ src/*~

Create the LICENSE file with a text editor.

$ vi LICENSE

Enter or copy the following text and save the file.

The Fibonacci application is public domain software.
For the purposes of this example we keep these statements in this file
but you should include the full text of the license here instead.

Build the binary from the fibonacci-rust-1.0 directory.

$ make build

cargo build --release
Compiling fibonacci-rust v0.1.0 (elxr_devpy/fibonacci-rust-1.0)
Finished release [optimized] target(s) in 0.30

Install the application.

sudo make install

cargo build --release
Finished release [optimized] target(s) in 0.03s
install -D target/release/fibonacci-rust /usr/local/bin/fibonacci-rust

Verify the installation was successful.

$ which fibonacci-rust
        /usr/local/bin/fibonacci-rust

Run the application to verify operation.
```
$ fibonacci-rust 5
0
1
1
2
3
```
Remove the Cargo.lock file to clean-up the build process files.
```
$ rm Cargo.lock
```

Create an archive of the application source.

$ make archive && cd ..

Once done, the folder structure should look like this:

$ tree

├── fibonacci-rust-1.0
│   ├── Cargo.lock
│   ├── Cargo.toml
│   ├── debian
│   │   ├── changelog
│   │   ├── control
│   │   ├── copyright
│   │   ├── rules
│   │   └── source
│   │       └── format
│   ├── fibonacci-rust-1.0.tar.gz
│   ├── LICENSE
│   ├── Makefile
│   ├── src
│   │   ├── fib_math.rs
│   │   └── main.rs
│   └── target
│       ├── CACHEDIR.TAG
│       └── release
│           ├── build
│           ├── deps
│           │   ├── fibonacci_rust-2a1211b65c6c9651
│           │   ├── fibonacci_rust-2a1211b65c6c9651.d
│           │   ├── fibonacci_rust-c29efe41c064abeb
│           │   └── fibonacci_rust-c29efe41c064abeb.d
│           ├── examples
│           ├── fibonacci-rust
│           ├── fibonacci-rust.d
│           └── incremental
└── fibonacci-rust-1.0.tar.gz

Note that when compared to the output source directory for a C or C++ application, the Rust application already includes a debian directory with subdirectories.

Results¶

Now that you have a working application prepared for packaging, you will need to run the debmake command to generate and update the package template files. For details, see Modifying Package Template Files for Rust Applications.