Rust / Usando a cargo

Bienvenidos sean a este post, hoy veremos algunas acciones que podemos hacer con cargo.

En el post anterior utilizamos tres comandos:

• new, para generar un nuevo proyecto
• build, se encarga de compilar el proyecto
• run, para ejecutar el proyecto compilado

Una cosa que no mencionamos es que en sistemas basados en Unix podemos utilizarlo de la siguiente forma:

cargo build; cargo run

Donde lo compilara y una vez finalizado procedera a ejecutarlo, veamos su salida:

tinchicus@dbn001vrt:~/lenguajes/rust/hola_mundo$ cargo build; cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
     Running `target/debug/hola_mundo`
Hello, world!
tinchicus@dbn001vrt:~/lenguajes/rust/hola_mundo$

Nota:
Puede que esto funcione en Windows pero no estoy completamente seguro, en Linux si me funciono.

Limpieza del arbol del codigo

Cuando compilamos un codigo fuente el script cargo genera unos archivos conocidos como archivos de objeto, estos toman el codigo fuente y lo compila en un formato al cual se le pueden unir otras librerias para poder generar el binario, esta es una buena practica porque recorta los tiempos de compilacion dado que si el codigo fuente no ha cambiado no es necesario volverlo a recompilar dado que el archivo objeto sera el mismo.

Pero en algunas ocasiones este archivo queda desactualizado o el codigo en otro archivo de objeto causa panico debido a conflictos entre ellos, para estos casos no es raro que se deba «limpiar la build», donde basicamente lo que hacemos es eliminar todos los archivos de objetos para que se deban recompilar nuevamente y generar los nuevos archivos de objetos.

Nota:
Una buena practica es realizar esto antes de pasar el programa a produccion.

Si debemos hacer una comparacion esta accion es muy similar al clean de make, make clean, dado que su sintaxis es la siguiente:

cargo clean

Vamos a aplicarlo en un ejemplo este es la estructura de nuestro proyecto en el post anterior luego de compilado y ejecutado:

tinchicus@dbn001vrt:~/lenguajes/rust/hola_mundo$ tree .
.
├── Cargo.lock
├── Cargo.toml
├── src
│   └── main.rs
└── target
    ├── CACHEDIR.TAG
    └── debug
        ├── build
        ├── deps
        │   ├── hola_mundo-a87193af95880929
        │   └── hola_mundo-a87193af95880929.d
        ├── examples
        ├── hola_mundo
        ├── hola_mundo.d
        └── incremental
            └── hola_mundo-kc1uw0blmg7c
                ├── s-g62kx6b6tx-afzog4.lock
                └── s-g62kx6b6tx-afzog4-tdpnhm9yx3sq
                    ├── 16gsk0kaaid6i5di.o
                    ├── 19p4xe29cww1qtpe.o
                    ├── 26fhxv80d1o4areb.o
                    ├── 29ypdvn515a1ab51.o
                    ├── 2eurlcvmpk9y4p2t.o
                    ├── 3veon29tccanryh5.o
                    ├── 43bgtkhma9xarvyd.o
                    ├── dep-graph.bin
                    ├── oebvkrjpnd8rx5g.o
                    ├── query-cache.bin
                    └── work-products.bin

9 directories, 20 files
tinchicus@dbn001vrt:~/lenguajes/rust/hola_mundo$

Si ejecutamos a clean nos quedara de la siguiente forma:

tinchicus@dbn001vrt:~/lenguajes/rust/hola_mundo$ tree .
.
├── Cargo.lock
├── Cargo.toml
└── src
    └── main.rs

1 directory, 3 files
tinchicus@dbn001vrt:~/lenguajes/rust/hola_mundo$

Como pueden ver no se preocupen porque el programa es lo bastante inteligente para hacer sus tareas, pasemos al siguiente tema.

Documentando el codigo

Al igual que sucede en la gran mayoria de los lenguajes se puede crear una documentacion del codigo que estamos trabajando, esto siempre es util para saber que hace esta libreria o de que se encarga este bloque del codigo, en general es una practica muy recomendada dado que por X motivo podemos dejar un codigo sin trabajar y cuando lo retomemos no sabremos donde lo dejamos y esto nos puede servir de guia.

El identificador para la documentacion es la triple barra (///), todo lo que este escrito detras de esto sera ignorado por cargo como codigo pero se transformara en documentacion, tomemos el codigo del post anterior y agreguemos un poco de documentacion:

main.rs

/// Este es un ejemplo de documentacion
/// 
/// de nuestro primer proyecto en Rust
/// 
/// a que no se ve bonito?

fn main() {
    println!("Hello, world!");
}

A diferencia de otros lenguajes siempre debe preceder o proceder a una funcion o bloque pero nunca debe quedar solo porque de lo contrario el compilador informara que esta documentacion no tiene ninguna utilidad y nos devolvera un error, pero tambien existe otra herramienta para crear documentacion.

Esta se llama rustdoc, este puede ser usado de forma independiente o llamado via cargo de la siguiente forma:

cargo doc

Dado que este hace un llamado a rustdoc desde el script, en cambio si lo usamos directamente sera de la siguiente forma:

rustdoc <codigo fuente>

En este caso debemos especificar cual es el archivo desde donde debe crear la documentacion, en ambos casos nos generara un directorio llamado doc pero la diferencia estara en que cargo lo crea en el directorio llamado target y rustdoc lo genera en el raiz del proyecto pero el contenido sera exactamente el mismo:

doc/
├── ayu.css
├── brush.svg
├── clipboard.svg
├── COPYRIGHT.txt
├── crates.js
├── dark.css
├── down-arrow.svg
├── favicon-16x16.png
├── favicon-32x32.png
├── favicon.svg
├── FiraSans-LICENSE.txt
├── FiraSans-Medium.woff
├── FiraSans-Medium.woff2
├── FiraSans-Regular.woff
├── FiraSans-Regular.woff2
├── LICENSE-APACHE.txt
├── LICENSE-MIT.txt
├── light.css
├── main
│   ├── all.html
│   ├── index.html
│   └── sidebar-items.js
├── main.js
├── normalize.css
├── noscript.css
├── noto-sans-kr-LICENSE.txt
├── noto-sans-kr-regular.woff
├── noto-sans-kr-regular.woff2
├── rustdoc.css
├── rust-logo.png
├── search-index.js
├── search.js
├── settings.css
├── settings.html
├── settings.js
├── SourceCodePro-It.ttf.woff
├── SourceCodePro-It.ttf.woff2
├── SourceCodePro-LICENSE.txt
├── SourceCodePro-Regular.ttf.woff
├── SourceCodePro-Regular.ttf.woff2
├── SourceCodePro-Semibold.ttf.woff
├── SourceCodePro-Semibold.ttf.woff2
├── source-files.js
├── source-script.js
├── SourceSerif4-Bold.ttf.woff
├── SourceSerif4-Bold.ttf.woff2
├── SourceSerif4-It.ttf.woff
├── SourceSerif4-It.ttf.woff2
├── SourceSerif4-LICENSE.md
├── SourceSerif4-Regular.ttf.woff
├── SourceSerif4-Regular.ttf.woff2
├── src
│   └── main
│       └── main.rs.html
├── storage.js
├── toggle-minus.svg
├── toggle-plus.svg
└── wheel.svg

Con esto «documentado» 😁 podemos pasar al siguiente tema.

Haciendo Testing

Esto es algo que ahondaremos mas adelante pero al igual que en la gran mayoria de los lenguajes podemos hacer un «test» de nuestro codigos, esto usualmente se denomina «unidad de test», esto puede hacer tanto en una funcion o metodo, asi como en una clase o un namespace pero solamente en librerias y no en archivos binarios, es decir programas ejecutables, no se preocupen que son temas que iremos desarrollando mas adelante, pero en todos los casos nos aseguran que funcionan correctamente.

Las unidades de testing en Rust son muy simples de crear, veamos un simple ejemplo:

fn main() { 
    println!("Tests no fueron compilados, use rustc --test en su lugar (o cargo test)"); 
} 
 
#[test] 
fn multiply_test() 
{ 
   if 2 * 3 == 5 
   { 
      println!("The multiply worked"); 
   } 
} 

Observen que la unidad que se testeara es la que esta entre los corchetes ([ ]) y junto al numeral (#), para este caso tenemos una funcion que verifica si la multiplicacion funciono o no, si les llama la atencion el condicional es porque no verifica si la multiplicacion devuelve ese resultado sino que se efectue correctamente, pero si nosotros necesitamos que se verifica el resultado en lugar de la operacion?.

Para ello entra en accion una serie de funciones llamadas assert donde verificamos distintos estados, en caso de necesitar verificar el resultado podemos usar assert_eq, tomemos la funcion anterior y modifiquemosla de la siguiente manera:

#[test] 
fn multiply() 
{ 
   assert_eq!(5, 2 * 3); 
} 

El primer valor sera el que debemos obtener, el segundo sera la operacion que verificaremos, en este caso solo obtendremos un true si 2 * 3 es igual a 5 y por ende pasara el test, pero sobre esto no se preocupen dado que ahondaremos mas en el tema mucho mas adelante, esto es un simple ejemplo de como cargo nos da la posibilidad de poder testear el codigo antes de compilarlo, para esto debemos usar la opcion de test al momento de llamar a cargo pero como dijimos mas adelante ahondaremos en este tema.

En resumen, hoy hemos visto varios aspectos que nos permite cargo, entre ellos como compilarlo y ejecutarlo al mismo tiempo, tambien hemos visto como crear una documentacion tanto con cargo como con rustdoc, por ultimo tambien hemos visto que tiene la posibilidad de poder hacer testing en nuestro codigo, espero les haya sido de utilidad sigueme en tumblr, Twitter o Facebook para recibir una notificacion cada vez que subo un nuevo post en este blog, nos vemos en el proximo post.