Ridgun

The language itself: a compiler that compiles itself, the stable project tool, the specification and the book

02-primeiros-pasos-e-ferramentas.md159 lines · 7.2 KBRaw

1	# Capítulo 02: Os teus dous mellores amigos: `ridgunc` e `stable` (Cero ficheiros YAML, prometido)
2
3	Hai linguaxes cuxo compilador é marabilloso, pero cuxo sistema de proxectos parece deseñado polo teu peor inimigo: que se un `Makefile` de 400 liñas con tabuladores invisibles, que se un `pom.xml` infinito, que se un `webpack.config.js` que deixa de funcionar se o miras fixo...
4
5	En Ridgun fixémonos unha promesa moi simple desde o primeiro día:
6
7	> "Só haberá dous executables en todo o ecosistema (`ridgunc` e `stable`), ambos estarán escritos no propio Ridgun, e o ficheiro de configuración do proxecto (`build.rg`) será código Ridgun normal e corrente. Nin JSON, nin YAML, nin TOML, nin inventos raros."
8
9	Imos ver como se usan.
10
11	---
12
13	## 2.1. `ridgunc`: O francotirador para ficheiros soltos
14
15	Cando tes un único ficheiro `.rg` entre mans e queres probar unha idea rápida, analizar os seus tipos ou compilar un executable, falas directamente con `ridgunc`.
16
17	Só ten 4 comandos que de verdade precisas lembrar:
18
19	```bash
20	# 1. "Compila isto ou metín a pata con algún tipo?"
21	ridgunc check experimento.rg
22
23	# 2. "Execútao xa!" (Compila e corre dun tirón)
24	ridgunc run experimento.rg
25
26	# 3. "Faime un binario nativo ELF listo para levar"
27	ridgunc build experimento.rg -o meu_programa
28
29	# 4. "Sácame o artefacto intermedio de bytecode (.rgc)"
30	ridgunc compile experimento.rg -o experimento.rgc
31	```
32
33	### O superpoder oculto de `ridgunc check`
34	Cando lanzas `ridgunc check`, non só che di "0 erros". Tamén che sopra que estratexia escolleu o analizador estático para cada unha das túas funcións:
35	- `InlineSequential`: "Esta función é pequeniña e directa; vouna executar en liña sen meter sobrecusto de planificación".
36	- `LazyStealableTask`: "Aquí hai recursión ou un grafo paralelo `\|\|`; prepároa para que outros núcleos de CPU poidan roubar traballo se fai falta".
37
38	### O bisturí de `ridgunc build` (Por que os teus binarios non pesan 20 MB)
39	Cando executas `ridgunc build`, o compilador non se limita a cuspir todo o código das bibliotecas que importaras:
40	1. Comeza na túa función `main` e percorre o grafo de chamadas para ver que funcións usas de verdade. Se importaches unha biblioteca enorme de 80 funcións pero só chamas a 2, as outras 78 descártanse antes sequera de tocar o ensamblador (Tree-Shaking).
41	2. Busca todas as funcións recursivas de cola e convérteas en bucles `loop` nativos que consumen 0 bytes de pila.
42	3. Pasa a ligazón final con optimización global (fat LTO) e limpa o lixo de depuración DWARF para deixarche un binario compacto e afiado (~350 KB).
43
44	---
45
46	## 2.2. `stable`: Cando o teu proxecto medra e queres orde
47
48	Un ficheiro solto está xenial para un script, pero en canto tes varios módulos, bibliotecas compartidas e probas, precisas un director de orquestra. Ese é `stable`.
49
50	A estrutura de cartafoles dun proxecto Ridgun non ten misterio:
51
52	```text
53	a-mina-super-ferramenta/
54	├── build.rg # O manifesto do proxecto (é código Ridgun!)
55	├── src/
56	│ ├── main/
57	│ │ └── ridgun/
58	│ │ ├── lib/ # Os teus módulos reutilizables (`import utilidades`)
59	│ │ └── app/
60	│ │ └── main.rg # Punto de entrada (`main => ()`)
61	│ └── test/
62	│ └── ridgun/ # As túas baterías de probas (`test *.rg`)
63	│ └── test todo.rg
64	└── target/ # Onde aparecen os binarios compilados
65	```
66
67	---
68
69	## 2.3. `build.rg`: Un ficheiro de configuración que nunca che mentirá
70
71	Por que nos negamos a usar YAML ou TOML para configurar un proxecto Ridgun?
72	Porque en YAML trabúcaste en dous espazos de sangrado e non te decatas ata que falla o despregamento. En cambio, como `build.rg` é un ficheiro Ridgun, ten tipos estáticos, pasa por `stable check` e alíñase só con `stable format`:
73
74	```ridgun
75	type ProjectInfo =
76	name: String
77	version: String
78	edition: String
79
80	project => ProjectInfo
81	project = ProjectInfo "a-mina-super-ferramenta" "0.1.0" "2026"
82
83	source dir => String
84	source dir = "src/main/ridgun"
85
86	test dir => String
87	test dir = "src/test/ridgun"
88
89	target dir => String
90	target dir = "target"
91
92	-- Opcional: activa o modo estrito de sinaturas e nomes (desactivado por defecto)
93	strict mode => Bool
94	strict mode = True
95	```
96
97	Se te trabucas ao escribir un campo, o propio compilador avísate. Sen sorpresas.
98
99	### O modo estrito (`--strict` / `strict mode = True`)
100	Por defecto, tanto `ridgunc` como os novos proxectos creados con `stable new` ou `stable init` teñen o modo estrito desactivado para que poidas prototipar con total liberdade. Cando queiras blindar o estilo canónico dun proxecto (como facemos no propio compilador de Ridgun), podes pasar `--strict` a `ridgunc` ou engadir `strict mode = True` ao teu `build.rg`. O modo estrito esixe dúas regras de elegancia:
101	1. Nomes de `fn ::` e `op ::` con espazos naturais, sen `_`: as declaracións deben usar espazos (`fn :: calcular imposto`, nunca `fn :: calcular_imposto`).
102	2. Retornos múltiples separados por espazos tras `=>`: cando unha función ou operador devolve varios valores, a súa sinatura de saída escríbese `=> Int Int` ou `=> Estado Int` (nunca `=> (Int, Int)` con parénteses nin comas).
103
104	---
105
106	## 2.4. A túa rutina diaria con `stable` (Os 4 fantásticos)
107
108	Cando estás traballando dentro do teu proxecto, o teu día a día redúcese a catro comandos:
109
110	### 1. `stable format` — A fin das discusións de estilo no equipo
111	```bash
112	stable format
113	```
114	Que o teu compañeiro pon tres espazos antes do `=>` e ti pos un? Dá igual. Executas `stable format` e en menos dun segundo deixa todos os ficheiros `.rg` do repositorio aliñados coma unha táboa suíza.
115
116	### 2. `stable check` — O radar instantáneo
117	```bash
118	stable check
119	```
120	Percorre todos os módulos de `src/main/ridgun/`, verifica tipos, construtores, aridades e dimensións de tensores, e dáche o veredicto módulo por módulo.
121
122	### 3. `stable test` — Durmir tranquilo polas noites
123	```bash
124	stable test
125	```
126	Busca todas as suites `src/test/ridgun/test *.rg`, execútaas e comproba cada `assert equals` e `assert true`.
127
128	```ridgun
129	-- Exemplo de src/test/ridgun/test mates.rg
130	import test
131
132	dobro Int => Int
133	dobro x = x * 2
134
135	main => ()
136	main =
137	assert equals (dobro 21) 42
138	assert true ((dobro 5) > 0)
139	```
140
141	### 4. `stable built` (e `stable clean`) — A produción
142	```bash
143	stable built
144	```
145	Compila todos os obxectivos nativos en `target/`. E se algún día queres borrar `target/` e comezar limpo: `stable clean`.
146
147	---
148
149	## 2.5. Como importo un ficheiro desde outro? (`import`)
150
151	Sen rutas relativas infernais tipo `../../../lib/cousas.rg`. Se tes un ficheiro `src/main/ridgun/lib/cadeas.rg`, en calquera outro ficheiro escribes arriba de todo:
152
153	```ridgun
154	import cadeas
155	```
156
157	E listo: todas as funcións e tipos de `cadeas.rg` están dispoñibles coma se estivesen no teu propio ficheiro. E que pasa se o módulo `A` fai `import cadeas`, o módulo `B` tamén fai `import cadeas`, e o teu `main.rg` importa `A` e `B`? Tranquilo: o cargador de Ridgun lembra que ficheiros canónicos leu xa e só o inclúe unha vez.
158
159	Agora que tes a caixa de ferramentas controlada, pasemos ao Capítulo 03 para dominar as funcións, os tipos, os bloques e os trucos con cadeas de texto.