how-i-build
Una vía de tren fotografiada a ras del riel, perdiéndose en el horizonte entre postes del tendido eléctrico
Estudio

Qué pasa cuando instalas Rust

Seguir el comando de instalación hasta el fondo: el script que descarga, los shims que planta en el PATH y dónde terminó el compilador de verdad.

10 min de lectura


Empecé a leer el Rust Book para entender de dónde viene el lenguaje, y terminé haciendo otra cosa: detenerme en cada comando antes de ejecutarlo. El capítulo 1 es corto y el libro claramente espera que lo pases de largo. Yo no lo hice — y lo que se escondía ahí tenía menos que ver con Rust que con cómo un programa llega a tu máquina.

El comando que nunca había leído

La instalación es una sola línea:

curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

curl es un cliente HTTP para la terminal. Hace lo mismo que un navegador cuando abres una URL: pide un recurso y recibe bytes. La diferencia es que, por defecto, vuelca esos bytes en pantalla en lugar de guardarlos en un archivo.

Eso ya respondió algo en lo que nunca me había detenido a pensar: a un endpoint HTTP no le importa ni sabe quién está del otro lado. Que los bytes que devuelve sean HTML, JSON o un script de shell es una convención, no una regla.

Todas las flags cuidan el canal: --proto '=https' rechaza cualquier cosa que no sea HTTPS, y --tlsv1.2 fija la versión mínima de cifrado aceptada. El -sSf silencia la barra de progreso pero mantiene visibles los errores, y hace que el comando falle ante un error HTTP — sin él, una página 404 se trataría como si fuera el script.

El | es la parte que importa. Es un pipe: conecta la salida de curl directamente con la entrada de sh. Lo que significa que el script nunca toca el disco. El shell lee el texto a medida que llega por la red y lo va ejecutando.

Por eso el patrón es polémico. Estás ejecutando código que no leíste, desde un servidor, con tus propios permisos de usuario.

Así que lo descargué sin ejecutarlo, solo para ver qué había ahí:

curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -o /tmp/rustup.sh
wc -l /tmp/rustup.sh

910 líneas. Y la sorpresa es que ninguna de ellas instala Rust.

El archivo es un despachador. Shell puro, portable, sin nada compilado dentro. Lo primero que hace es preguntarle a la máquina quién es:

uname -s   # sistema operativo
uname -m   # arquitectura del procesador

Guarda las dos respuestas, y más abajo las une en una sola cadena:

_arch="${_cputype}-${_ostype}"               # línea 576
_url="${_url}/${_arch}/rustup-init${_ext}"   # línea 104

En mi máquina eso da x86_64-unknown-linux-gnu. Esa cadena es la que se convierte en la URL del binario correcto.

La razón es algo que sabía de C pero que nunca había visto pasar frente a mí: un binario compilado es código de máquina, específico de un procesador y de un formato de ejecutable. Un .exe de Windows no corre en Linux, y un binario ARM no corre en x86. Como hay decenas de combinaciones posibles, la única forma de meter esto en un solo comando es enviar primero un script liviano — uno que averigüe el destino y traiga solo la pieza correcta.

Un detalle me llamó la atención: no mira la distro. No hay un "build para Arch" y otro "para Ubuntu". Lo que importa es el sistema, el procesador y la libc — la biblioteca C del sistema, gnu o musl. La distro es irrelevante para el binario.

Adónde fue Rust en realidad

Terminada la instalación, el libro dice que ejecutes rustc --version y sigas. Yo fui a mirar la carpeta primero:

ls ~/.cargo/bin
cargo -> rustup          rust-analyzer -> rustup
cargo-clippy -> rustup   rust-gdb -> rustup
cargo-fmt -> rustup      rustc -> rustup
clippy-driver -> rustup  rustdoc -> rustup
rls -> rustup            rustfmt -> rustup

Todos son symlinks — accesos directos que no contienen nada, solo apuntan a otro archivo. Y todos apuntan al mismo lugar.

Así que el rustc de mi PATH no es el compilador. Es rustup disfrazado. Eso tiene nombre: un shim, un intermediario que recibe la llamada y la pasa.

El compilador de verdad vive en otro lado:

ls ~/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/bin/

Aquí se deshizo la confusión que venía cargando. Yo creía que rustup era Rust, porque todo estaba dentro de su carpeta. No lo es. rustup es el encargado del almacén: no compila nada, guarda las herramientas y te entrega la correcta cuando la pides. ~/.rustup es solo el armario.

Los tres nombres, sin superposición:

  • rustc — el compilador. Convierte .rs en un binario.
  • cargo — sistema de build y gestor de paquetes. Llama a rustc por ti y se encarga de las dependencias.
  • rustup — gestor de versiones. Instala toolchains y decide cuál está activa. Es el equivalente de nvm, no de npm.

Lo que plantea la pregunta obvia: ¿para qué el teatro de los accesos directos? Si el compilador está en una carpeta, ¿por qué no poner esa carpeta en el PATH y listo?

Porque pueden coexistir varias toolchains — stable, nightly, beta, una versión fija como 1.75.0 — cada una con su propio rustc. Si la carpeta de la toolchain estuviera directamente en el PATH, cambiar de versión implicaría reescribir el PATH cada vez, y no podrías tener un proyecto en stable y otro en nightly al mismo tiempo.

El shim lo resuelve decidiendo en el momento de la llamada. Revisa si hay un rust-toolchain.toml en la carpeta, si hay un override configurado para ese directorio, si el comando llegó como cargo +nightly. Solo entonces elige qué rustc ejecutar. El mismo truco que nvm, pero por directorio y sin ningún nvm use que recordar.

Del texto al binario

El rustc main.rs del libro produce un archivo llamado main. Lo que yo quería saber era qué hizo exactamente.

El punto de partida es que el procesador no entiende texto. Entiende números, y cada número es una instrucción: suma esto, salta allá, escribe aquí. Eso es todo lo que sabe leer. Mi main.rs son 45 bytes de letras que yo entiendo y él no — fn y println! no significan nada para el silicio.

Compilar es traducir. Puedes ver los dos lados:

cat main.rs        # legible, es mi código
head -c 200 main   # ELF, y después lo que parece basura

No es basura. Son los números que entiende el procesador, con la terminal intentando mostrar cada byte como si fuera una letra. El ELF del principio es la etiqueta del formato de ejecutable de Linux — es como el sistema reconoce el archivo después.

La traducción no ocurre de una sola vez. rustc pasa el código por una línea de montaje:

  1. Leer el texto. Partirlo en piezas con significado — esto es una función, esto es una llamada, esto es una cadena — y armar un árbol en memoria. Una llave faltante muere aquí.
  2. Comprobar que tenga sentido. ¿Coinciden los tipos? ¿Existe la variable? ¿Quién es dueño de cada valor? Aquí vive el borrow checker, y esta etapa es la que hace que Rust sea Rust.
  3. Simplificar y optimizar. Reescribir el código en una forma interna más cruda y recortar el desperdicio.
  4. Emitir código de máquina. Los números.
  5. Enlazarlo todo. Mi código solo no corre: llama a println!, que vive en la biblioteca estándar. El linker pega las piezas en un único ejecutable — por eso el libro advierte que necesitas un linker instalado.

Puedes ver la etapa 2 por separado declarando un entero y metiéndole una cadena: el compilador entiende el código perfectamente y rechaza el significado.

Después de la etapa 5, rustc termina y desaparece. Compilar y ejecutar son dos actos separados, y el segundo no es trabajo suyo. Cuando escribo ./main, el que actúa es el sistema operativo: lee el archivo, ve la etiqueta ELF, carga los números en memoria y apunta el procesador al punto de entrada.

La consecuencia práctica es que puedo borrar main.rs y ./main sigue corriendo. Y puedo pasarle ese binario a alguien que no tiene Rust instalado.

Una pregunta tonta me seguía molestando: ¿por qué 45 bytes de texto se convirtieron en un archivo de 4.4 MB? Hay dos razones, y puedes medirlas por separado pasando strip sobre el binario, que elimina la información de depuración.

La primera es que ahí dentro no está solo mi código. En la etapa 5 el linker pegó la biblioteca estándar — println! no es mío, es código ya hecho que ahora vive dentro de mi ejecutable. Eso representa unos 340 KB.

El resto, casi todo el tamaño, es un mapa: un índice que vincula cada tramo de código de máquina con el archivo .rs, con nombres de funciones y números de línea. Es lo que permite que un programa que se cae diga "línea 3 de main.rs" en vez de escupir una dirección de memoria.

Cargo y los tres archivos

rustc a mano solo te lleva hasta un archivo suelto. A partir de ahí el libro pasa a cargo, y esta es la parte que ya reconocía de otro lado.

El problema que resuelve un gestor de paquetes es siempre el mismo: nadie escribe todo desde cero, y en cuanto dependes del código de otra persona aparecen cuatro dolores — dónde lo encuentro, cómo lo descargo, qué versión, y qué pasa cuando esa biblioteca depende de otras tres. En Rust una biblioteca publicada se llama crate, y viven en crates.io.

El paralelo es directo: cargo es a npm lo que un crate es a un paquete y crates.io al registry. La diferencia es que cargo hace más — también es el sistema de build, el que llama a rustc por ti. En el mundo JS sería npm y vite en una sola herramienta.

Un proyecto nuevo empieza con un Cargo.toml:

[package]
name = "hello_cargo"
version = "0.1.0"
edition = "2024"

[dependencies]

TOML es un formato de configuración, como JSON o YAML pero pensado para que lo lea una persona: [algo] abre una sección y dentro vienen líneas clave = valor. La edition es la cosecha de Rust — el lenguaje cambia de dialecto cada pocos años sin romper el código viejo.

El punto central es que este archivo lo escribo yo. Es una declaración de intención, y cargo nunca inventa nada ahí por su cuenta. Al ejecutar cargo add rand, la sección vacía gana una línea:

[dependencies]
rand = "0.10.2"

Parece una versión exacta, pero no lo es. Es un rango: 0.10.2 o cualquier versión posterior compatible — 0.10.7 sirve, 0.11 no. Cargo.toml es vago a propósito: dice lo que acepto, no lo que tengo.

Y apareció un archivo que nunca pedí, Cargo.lock. Conté los paquetes que lista:

grep -c '^\[\[package\]\]' Cargo.lock

Nueve. Yo había pedido uno. rand depende de otros crates, que dependen de más, y cargo siguió la cadena hasta el final y los anotó todos — eso es una dependencia transitiva.

La diferencia entre los dos archivos es exactamente esa: el .toml es lo que quiero, corto y vago; el .lock es lo que tengo, largo y exacto, con la versión precisa de cada uno de los nueve más un checksum de cada uno. Sin el .lock yo compilaría hoy contra 0.10.2 y otra persona compilaría mañana contra 0.10.3 — y si 0.10.3 trae un bug, el programa se rompe en su máquina y no en la mía. Solo cambia cuando yo lo digo, con cargo update.

Después del primer cargo build aparece la tercera pieza, target/. Son 27 MB para un programa que imprime una frase, y tiene sentido: adentro están los nueve crates compilados uno por uno, mi binario y caché para que el siguiente build no rehaga todo. Lo que importa es que es desechable — ahí no vive nada de valor único, y borrarlo solo cuesta tiempo. El .gitignore que genera cargo tiene una sola línea, y es esa carpeta.

Cerrando los tres: Cargo.toml es lo que quiero y lo escribo yo; Cargo.lock es lo que tengo y lo escribe cargo; los dos van a Git. target/ es salida de build y queda fuera, porque se puede regenerar a partir de los otros dos.

Eso también aclaró qué significa "build", que es más amplio que compilar. Cuando ejecuto cargo build, lee el .toml y el .lock para saber qué hace falta, descarga lo que falta al caché global en ~/.cargo/registry, llama a rustc una vez por cada uno de los nueve crates, lo llama de nuevo para mi código y lo enlaza todo en un ejecutable. cargo es el maestro de obra y rustc es el albañil: esa línea de cinco etapas corre diez veces aquí, una por crate.

Los dos modos de build eran lo último que faltaba, y eso preferí medirlo. Escribí un programa que suma 500 millones de cuadrados y cronometré ambos binarios:

debug     3.65 s
release   1.81 ms

Dos mil veces de diferencia. Pero la conclusión no es "release es más rápido" — 500 millones de iteraciones en 1.8 ms serían 275 mil millones de vueltas por segundo, algo que mi procesador no puede hacer. El bucle nunca corrió. El optimizador vio que el resultado no depende de nada externo, calculó el valor en tiempo de compilación, y el binario de release básicamente solo imprime un número que ya tenía.

Eso es lo que significa optimizar: el compilador tiene libertad para reescribir el código como quiera, siempre que el resultado observable sea el mismo. El precio es el tiempo de compilación, y por eso existen los dos modos — debug compila rápido, corre lento y lleva el mapa que hace decentes los mensajes de error; release compila lento y corre rápido. Por eso cargo run usa debug por defecto: en el día a día recompilo decenas de veces por hora y ejecuto una.


El capítulo 1 del libro cabe en quince minutos. A mí me llevó una tarde, y lo que me quedó no fue la sintaxis de Rust — fue entender que el comando de instalación es un script que averigua cómo es mi máquina, que el rustc del PATH es un acceso directo, que el binario lleva la biblioteca estándar adentro, y que build y compilación no son lo mismo. Nada de eso es específico de Rust. Solo estuvo siempre escondido detrás de un comando que yo copiaba sin leer.