3 · Référence CLI

Synopsis

amc [options] file1.am [file2.am ...] -o <output>     # compile
amc <subcommand> [args...]                            # autres commandes

Le compilateur émet toujours un fichier .c. Pour produire un binaire natif, enchaînez avec gcc :

amc hello.am -o hello                                    # → hello.c
gcc -Iruntime hello.c -lgc -lm -o hello           # → hello (binaire)
./hello

Les en-têtes du runtime se trouvent dans runtime/ à la racine du projet.

Sous-commandes

Chaque sous-commande gère ses propres flags et codes de sortie ; consultez le chapitre référencé ou --help pour la surface complète.

amc package <action> (alias amc pkg)

Opérations de packages locales au projet. Toutes les actions lisent/écrivent amalgame.toml (dépendances) et amalgame.lock (SHAs Git résolus) dans le répertoire de travail courant.

amc test installe automatiquement toute dépendance manquante avant d'exécuter la suite, et lie les objets C vendorisés de [stdlib].sources de chaque package dans chaque binaire de test — les backends comme SQLite « fonctionnent sans configuration » sans flags gcc manuels. Depuis la v0.5.3, les sources .cpp / .cc / .cxx sont compilées avec g++ (et la liaison finale du test passe par g++ quand un package contribue du C++), ce qui permet aux packages vendorisant une amalgamation C++ dans le style DuckDB de fonctionner immédiatement.

Référence du manifeste amalgame.toml

Le fichier amalgame.toml d'un package décrit à la fois ses métadonnées ([package]) et la surface qu'il apporte aux consommateurs ([stdlib]). Le amalgame.toml d'un projet utilisateur ne contient généralement que [package] + [dependencies].

[package]
name              = "amalgame-database-duckdb"
version           = "0.1.0"
license           = "Apache-2.0"
required-amalgame = ">=0.5.3"   # refuses install on older amc
schema-version    = 1           # refuses install on amc < this schema

[stdlib]
class     = "DuckDB"
header    = "runtime/Amalgame_Database_DuckDB.h"
namespace = "Amalgame.Database.DuckDB"
sources   = ["runtime/Amalgame_Database/duckdb/duckdb.cpp"]
cflags    = ""                  # extra flags for .c sources
cxxflags  = "-O3 -DNDEBUG -std=c++17"  # extra flags for .cpp/.cc/.cxx
libs      = ["stdc++"]          # bare names → -l<name> at link time

[stdlib.functions]
Open     = { returns = "AmalgameDuckDB*" }
Close    = { returns = "void" }
# Optional `returns_generic` (v0.8.40+) carries the AM-level
# generic shape so chained `.Get(i).Get(j)…` on the consumer side
# infers typed casts instead of falling through to `(void*)`.
# Example: `QueryAll` returning rows-of-columns of strings.
QueryAll = { returns = "AmalgameList*", returns_generic = "List<List<string>>" }
# …

Opérateurs required-amalgame (v0.6.0+)

La chaîne de contrainte suit les conventions npm/Cargo. Exemples :

Les opérateurs non reconnus sont traités comme « pas de contrainte » (retourne vrai) afin de maintenir la compatibilité des anciens binaires amc avec les futures extensions de syntaxe.

Résolution automatique amc package add <pkg> (v0.6.0+)

Quand le suffixe @<tag> est omis sur un nom court indexé, amc récupère l'index et choisit le tag le plus récent dont le required-amalgame est satisfait par l'amc en cours :

$ amc package add duckdb
Auto-resolved 'duckdb' → 'duckdb@v0.1.1' (latest compatible with amc 0.6.0)
…

Les URLs git complètes nécessitent toujours un @<tag> explicite — l'index est la source de vérité pour « ce qu'amc connaît », et les dépôts non indexés se désinscrivent de la résolution automatique par conception.

Si aucune version n'est compatible (par exemple, tous les tags indexés requièrent un amc plus récent que celui installé), la commande échoue avec une indication invitant à exécuter amc package versions <pkg> pour obtenir la liste complète des contraintes.

Options

Tout argument positionnel se terminant par .am est traité comme un fichier d'entrée. Les options inconnues provoquent une erreur avec un message d'usage.

Codes de sortie

Le compilateur tente de progresser malgré les avertissements du résolveur — il arrive souvent qu'un fichier .c soit généré en même temps que des diagnostics. Fiez-vous au code de sortie comme source de vérité, pas à la présence du fichier .c.

Compilation multi-fichiers

Passez plusieurs fichiers .am ; le compilateur les fusionne, exécute toutes les passes sur l'union et émet un seul fichier .c :

amc lexer.am parser.am main.am -o myapp

La directive namespace du premier fichier détermine le préfixe des symboles C pour l'ensemble de l'unité de compilation — placez donc le fichier le plus autoritaire en premier (ou assurez-vous que tous les fichiers partagent le même namespace).

Program.Main de main.am devient le point d'entrée du binaire. Si plusieurs fichiers déclarent Program.Main, le compilateur C rejettera les symboles en double à l'édition de liens — un seul point d'entrée par exécutable.

Mode bibliothèque

amc --lib mylib.am -o mylib
# → mylib.c (no int main, marked "[Library]")
gcc -Iruntime -c mylib.c -o mylib.o
# Link mylib.o from a host program — see chapter 5 for C interop.

Détection automatique : un fichier sans Program.Main est automatiquement traité comme une bibliothèque (aucun flag --lib nécessaire).

amc build / run / watch (depuis v0.7.9)

Le verbe de compilation de premier rang. amc build exécute amc sur le fichier d'entrée et invoque gcc avec les bons flags (en-têtes du runtime, lib/libamalgame.a, archives de façades des packages installés, fichiers .o vendorisés des packages, [stdlib].libs déclarés par chaque package). Le résultat est un binaire exécutable — sans étape gcc séparée.

amc build hello.am             # produces ./hello
amc build -o myapp src/main.am # explicit output
amc build -v hello.am          # verbose: prints the gcc command
amc build -g hello.am          # debug build (-O0 -g for `amc dap`)

Le flag -g / --debug (v0.8.0+) remplace -O2 par -O0 -g à la fois pour la liaison gcc en une étape et pour le chemin C++ en deux étapes (DuckDB, etc.). Le cgen émet des directives #line N "foo.am" à chaque statement, de sorte que DWARF transporte les noms de fichiers .am et les numéros de ligne — les débogueurs placent directement les points d'arrêt sur les sources .am, sans source maps. Voir amc dap au chapitre 6 et le workflow de débogage en fin de chapitre 6.

amc run enchaîne une compilation avec Process.Run sur le binaire résultant. Les arguments après le sentinel -- sont transmis à l'argv du programme utilisateur :

amc run hello.am               # build then run, no user args
amc run server.am -- --port 8080 --verbose

amc watch compile une fois, puis surveille le mtime du fichier d'entrée toutes les 500 ms et reconstruit à chaque modification. Avec --run, il ré-exécute également le binaire après chaque reconstruction réussie — pratique pour les boucles de développement :

amc watch --run server.am      # rebuild + restart on save
amc watch hello.am             # rebuild only (manual ./hello to run)

La v1 surveille uniquement le fichier d'entrée explicitement nommé en ligne de commande. Les imports transitifs sont hors périmètre jusqu'à ce que le package Amalgame.IO.FileWatcher dispose d'un mode événementiel (post-D dans la roadmap).

La forme avec arguments positionnels amc foo.am -o foo fonctionne toujours (émet uniquement foo.c — sans étape gcc) et reste supportée pour les cas limites où les utilisateurs souhaitent brancher leur propre commande gcc (cross-compilation CI, flags personnalisés, cibles embarquées).

Workflows typiques

Test rapide d'un fichier unique

amc build hello.am && ./hello   # since v0.7.9
# OR the explicit two-step form
amc hello.am -o hello
gcc -Iruntime hello.c -lgc -lm -lz -o hello
./hello

Vérification de types à la sauvegarde (intégration éditeur)

amc --check --no-color foo.am
echo $?     # 0 = OK, 1 = errors printed on stderr

Compilation d'un projet multi-fichiers

Depuis la v0.7.9, amc build avec un point d'entrée unique couvre la plupart des cas — amc résout les instructions import transitivement depuis l'entrée, il suffit généralement de :

amc build src/main.am          # → ./main

Pour les anciennes versions v0.7.x (ou pour un contrôle explicite sur la liste de fichiers), la forme en deux étapes fonctionne toujours :

amc \
    src/util/strings.am \
    src/util/collections.am \
    src/server/router.am \
    src/main.am \
    -o build/app

gcc -O2 -Iruntime build/app.c -lgc -lm -o build/app

Recompilation du compilateur lui-même

./build_amc.sh        # ~5s, full self-host (runs amc on its own sources)

Le comportement de ce script est décrit au chapitre 6.

Environnement

Le CLI est hermétique — il ne lit pas les variables d'environnement. Les en-têtes du runtime côté compilation proviennent de gcc -I<runtime-dir>.

Débogage du compilateur

Si amc produit du C invalide, réduisez l'entrée en supprimant la moitié jusqu'à ce que l'échec disparaisse, puis signalez le problème avec la reproduction minimale. Flags utiles lors du tri :

• --quiet pour faire taire les messages « OK » et se concentrer sur les erreurs
• --no-color afin que la sortie des extraits reste compatible avec grep
• Inspectez directement le fichier .c émis — le nommage suit <Namespace>_<Class>_<Method> et se prête bien à grep.

Pour les détails internes approfondis (comment le pipeline parcourt l'AST, où ajouter un nouveau builtin, comment le CGen émet une fonctionnalité), voir le chapitre 7.