diff --git a/tmg-documentation/tutorials/Rust/PyO3Maturin.md b/tmg-documentation/tutorials/Rust/PyO3Maturin.md new file mode 100644 index 00000000..c06e70c1 --- /dev/null +++ b/tmg-documentation/tutorials/Rust/PyO3Maturin.md @@ -0,0 +1,33 @@ +# PyO3 Maturin + + +## link to Library +https://github.com/PyO3/pyo3 + + +### Installation and Setup + +``` +# (replace string_sum with the desired package name) +$ mkdir string_sum +$ cd string_sum +$ python -m venv .env +$ source .env/bin/activate +$ pip install maturin + + +Still inside this string_sum directory, now run maturin init. This will generate the new package source. When given the choice of bindings to use, select pyo3 bindings: + +$ maturin init +What kind of bindings to use? · pyo3 +Done! New project created string_sum + +``` +``` +$ maturin develop +# lots of progress output as maturin runs the compilation... +$ python +>>> import string_sum +>>> string_sum.sum_as_string(5, 20) +'25' +``` \ No newline at end of file diff --git a/tmg-documentation/tutorials/Rust/index.md b/tmg-documentation/tutorials/Rust/index.md new file mode 100644 index 00000000..7795f564 --- /dev/null +++ b/tmg-documentation/tutorials/Rust/index.md @@ -0,0 +1,112 @@ +# Overview + +## Rust +Rust is a strongly typed, memory-safe system programming language designed to ensure high performance without sacrificing +safety. It emphasizes concurrent programming, providing mechanisms to prevent data races at compile time. +Rust’s ownership model, combined with strict compile-time checks, allows developers to write robust and efficient code with +a focus on reliability, speed, and maintainability. Its expressive syntax, rich standard library, +and modern tooling make Rust suitable for both system-level development and high-level application programming. + + +## The rust documentation: + +* [Rust Book](https://doc.rust-lang.org/cargo/) - This link is the rust book that goes into the both the basics and advanced concepts of how to use Rust. +* [Rustlings](https://rustlings.rust-lang.org/) - An online (or optionally offline) tool to learn Rust through a series of problems. + +## Installation Instruction: + + +### Tools Needed: + +You do need a code editor and choose any code editor of your choosing. The two recommended code editors are Visual Studio(Windows) +or Visual Studio Code. Download links provided below: +* [Visual Studio Code](https://code.visualstudio.com/download) - Windows, Mac and Linux +* [Visual Studio](https://visualstudio.microsoft.com/downloads/) - Windows only + + +## Installing Rust Instructions +The main installation instructions can be found at this link: +- https://rust-lang.org/tools/install/ + + +The main page will then give you the terminal command lines needed to install Rust depending on your system and machine configurations. + +### Installing Rust on Windows: +On Windows, the application is distributed as a downloadable executable file. After downloading it from the website, +you can install it by double‑clicking the file. + + + +### Installing Rust on Linux: +On Linux, the application gives you a command you can copy paste into your terminal and click enter to run. +``` +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +## Cargo +Cargo is Rust’s official build system and package manager, providing an efficient way to install, manage, and compile project dependencies. It streamlines the process of creating, organizing, and building Rust projects. +The following commands are particularly useful: + +To create a new project that will create a folder with the base template files: +```> cargo new hello_world + Creating binary (application) `hello_world` package +note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html +``` + +The command creates the following tree: +``` +F:. +│ .gitignore +│ Cargo.lock +│ Cargo.toml +│ +└───src + main.rs +``` +As you can the command generates one folder called src that has the main basic file called main.rs file which is the main rust file. The Cargo.toml file is the file which will manage and list all +the libraries and tools you will use for your project. + Cargo.toml + +To run a rust application run the command cargo run like below + +``` +> cargo run +``` + +If you use the ls command you will see a new folder called target which stores the compiled binaries and dependenices for your project + +If you wish to just build your application and not run it you can use cargo build +``` +> cargo build +``` + +Cargo clean is used to clean the project during errors. +``` +> cargo clean +``` + +``` +> cargo doc +> cargo doc -open +``` +Cargo doc is a useful command line as it reads your rust code and automatically generates all the documentation for your project. +It productes a html file that can be opened in any browser. +With the open command the documentation is automatically opened in the browser by the system default browser. + +Here is an example of how to add libraries to the cargo. You use the command Cargo add for example +``` +> cargo add polars --features lazy,csv +``` +- Note: the features command allows you to install the libary methods you wish and need. + +Upon successful completion opening your Cargo.toml file in the text editor under dependencies will show the installed libraries +with the version. +Below is an example of a Cargo.toml file with some installed packages. +``` +[dependencies] +csv = "1.4.0" +polars = { version = "=0.51.0", features = ["lazy", "bigidx"] } +serde = "1.0.228" +``` + + \ No newline at end of file diff --git a/tmg-documentation/tutorials/Rust/toc.yml b/tmg-documentation/tutorials/Rust/toc.yml new file mode 100644 index 00000000..64526716 --- /dev/null +++ b/tmg-documentation/tutorials/Rust/toc.yml @@ -0,0 +1,5 @@ +- name: Overview + href: index.md + +- name: Python Maturin + href: PyO3Maturin.md \ No newline at end of file diff --git a/tmg-documentation/tutorials/toc.yml b/tmg-documentation/tutorials/toc.yml index 88b79ed5..5aebea31 100644 --- a/tmg-documentation/tutorials/toc.yml +++ b/tmg-documentation/tutorials/toc.yml @@ -12,3 +12,6 @@ - name: Population Zone System Conversion in QGIS href: PopZoneSysConversionQGIS/toc.yml homepage: PopZoneSysConversionQGIS/index.md +- name: Rust Tutorial + href: Rust/toc.yml + homepage: Rust/index.md