Come risolvere i guasti negli autotools

1.  Introduzione

Con il termine autotools ci riferiamo solitamente agli strumenti sviluppati dal progetto GNU per creare un sistema di compilazione indipendente dalla piattaforma e dal sistema operativo in cui opera, ovvero autoconf, automake e libtool. Anche se non ogni pacchetto li usa tutti allo stesso momento, molti dei più moderni lo fanno; i vecchi pacchetti spesso non usano invece automake e libtool; i pacchetti di KDE usano un più complesso sistema di compilazione che si basa alla fine sui tre software citati.

È semplice riconoscere un pacchetto il cui sistema di compilazione si basa sugli autotools: se c'è uno script configure, e un file configure.in o configure.ac, il sistema di compilazione è basato su autoconf; se ci sono uno o più file Makefile.am nelle varie sottocartelle, si appoggia anche su automake; se c'è uno script ltmain.sh, sfrutta infine libtool.

Per compilare un pacchetto che usa un sistema di compilazione basato sugli autotools, questi stessi strumenti non sono strettamente necessari: lo script configure è un semplice script per Bourne Shell (di solito, ma questo sarà discusso in seguito) e trasforma i file Makefile.in in più semplici Makefile per make (o, più probabilmente, gmake). Nonostante siano opzionali per compilare il software, spesso le patch necessarie per risolvere i problemi come le compilazioni fallite a causa di --as-needed (ndT: in inglese) o le dipendenze automagic richiedono di eseguire nuovamente gli strumenti citati per ricreare i modelli di script e makefile.

Questa guida non darà indicazioni su come correggere gli errori dei pacchetti con l'uso degli autotools, in quanto è un argomento molto vasto che richieder ebbe molto tempo per essere spiegato. Per una semplice introduzione alla maggior parte degli errori più comuni nell'uso degli autotools, è caldamente suggerito la lettura dell'articolo "Le migliori tecniche con gli autotools". Invece, saranno descritti i casi più comuni in cui il rieseguire gli autotools porta a degli errori, sia nella creazione degli script che all'atto della compilazione.

2.  Eseguire nuovamente gli autotools

La prima cosa importante da sapere è come ricreare correttamente il supporto agli autotools, problema comune che introduce degli errori negli ebuild. L'ordine in cui gli autotools sono eseguiti è importante, in quanto uno dipende dall'altro e l'output finale dipende largamente dal rispetto dell'ordine di esecuzione.

Molti pacchetti forniscono uno script singolo, solitamente chiamato autogen.sh o bootstrap.sh che viene usato per eseguire i vari strumenti nell'ordine che gli sviluppatori originali ritengono essere quello corretto, spesso impostando variabili così che le versioni corrette di tali strumenti vengano eseguite (versioni differenti degli autotools non sempre vanno bene). Questi script sono, in generale, preferiti al posto di altri metodi ma a volte contengono errori, o assumono di essere eseguito su un dato ambiente che potrebbe essere univoco rispetto ad altre distribuzioni, e per questa ragione vanno controllati attentamente, e quando non comportano nessun vantaggio rispetto ad altri metodi (come nel caso in cui eseguono i vari strumenti uno dopo l'altro senza passare loro parametri speciali o controllare il loro valore di ritorno), dovrebbero essere scartati.

Il pacchetto autoconf fornisce uno script automatizzato, chiamato autoreconf che dovrebbe automaticamente rilevare quali autotools sono utilizzati e chiamarli, ma troppo spesso fallisce nel riconoscere la corretta versione o si interrompe perchè incappa in casi specifici. Inoltre, esegue autopoint, lo script che aggiunge il supporto a gettext ad un pacchetto, la cui esecuzione non è quasi mai richiesta dopo aver applicato patch ad un pacchetto. Per questa ragione, autoreconf è deprecato ed evitato quando possibile (lo stesso vale per gli script forniti dagli sviluppatori originali che lo usano).

Per aggirare questo problema, è stata aggiunta l'eclass autotools, che fornisce delle funzioni che inglobano gli GNU autotools: eautoconf, eautomake, _elibtoolize (il simbolo _ è usato come prefisso per evitare collisioni con le funzioni elibtoolize provenienti invece dall'eclass libtool) e la più importante funzione eautoreconf. Questa funzione non include lo script autoreconf malfunzionante, ma piuttosto analizza i file di supporto agli autotools presenti ed esegue i vari strumenti nel loro corretto ordine. Inoltre esegue la funzione elibtoolize per correggere i file di supporto a libtool se necessario, evitando problemi quando questo viene chiamato prima dell'attuale ristrutturazione dei file per gli autotools.

Le funzioni nell'eclass autotools hanno anche il vantaggio di non presentare all'utente grosse quantità di output inutile (nel caso di avvertimenti) o perfino niente (in caso non ci siano problemi); piuttosto forniscono i messaggi di stato ebegin/eend così che l'utente saprà cosa sta succedendo, e inoltre tracciano la situazioni d'errore mettendo a disposizione un messaggio simile a epatch in caso di fallimento. Per tale ragione, queste funzioni sono preferite al posto delle chiamate manuali, di comportamenti scorretti o script personalizzati quasi inutili. Un altro motivo è che l'eclass autotools aggiunge anche una dipendenza di compilazione sui pacchetti di cui necessita (sys-devel/autoconf, sys-devel/automake, sys-devel/libtool).

Casi eccezionali: pacchetti KDE che usano kde.eclass

Nonostante KDE 3.x usi gli autotools come molti altri pacchetti software, sta impiegando un'impostazione personalizzata per essi con diverse macro specifiche e passaggi aggiuntivi utili a completare la rigenerazione di tutti i file necessari. Per questa ragione gli autotools non dovrebbero essere usati per ricompilare gli autotools per pacchetti KDE che usano la eclass kde per la compilazione.

Come particolare eccezione alle regole comuni per la ricompilazione degli autotools durante la fase di src_unpack, i pacchetti KDE ricompilano i propri autotools durante la fase src_compile ogni volta che il file principale configure non viene trovato. Per questa ragione, per chi volesse ricompilare i file degli autotools per pacchetti KDE, assicurarsi prima di rimuovere il file configure dalla cartella principale dei sorgenti.

Molti dei problemi sollevati dal sistema di compilazione personalizzato di KDE, che compaiono con le nuove versioni degli autotools, possono essere di solito risolti rimpiazzando la cartella admin nell'archivio dei sorgenti con una nuova copia presa dall'ultimo rilascio di KDE o da SVN. Per farlo basta aggiungere un archivio, contenente la nuova cartella admin come unica contenuto della variabile SRC_URI, sarà poi kde_src_unpack a prendersi cura del rimpiazzo.

3.  Casi comuni di fallimento e cause

Possibili macro non definite

Il fallimento più comune con gli autotools è legato al messaggio di autoconf "possibly undefined macro: SOME-MACRO" ("possibile macro non definita: QUALCHE_MACRO"). Questo messaggio è utilizzato quando una macro viene chiamata dal file configure.ac o configure.in ma non è in realtà definita nel file aclocal.m4 creato da aclocal.

Questo succede spesso perchè la macro indicata non è disponibile quando aclocal viene eseguito; poiche, in modo predefinito, si caricano le macro trovate in /usr/share/aclocal, ciò significa che il pacchetto che fornisce questa macro non è installato (o la macro è chiamata con un altro nome). Siccome il secondo caso è tanto banale quanto complesso da risolvere, ci si concentrerà sul primo esempio, la definizione mancante di una macro.

Affinchè le macro scritte dagli sviluppatori originali per il loro software siano rilevate nel sistema dall'uso degli autotools, vengono normalmente scritte in file m4 che sono poi installati nella già citata cartella /usr/share/aclocal. Dato che molti pacchetti usano queste macro per le dipendenze opzionali, potrebbero avere bisogno di un file m4 che non è installato nel sistema quando vengono eseguiti gli autotools; per risolvere il problema, è possibile copiare il file m4 in una sottocartella fornita del pacchetto stesso.

Sfortunatamente, per poter utilizzare questa sottocartella, di norma chiamata m4, aclocal deve essere informato riguardo alla sua esistenza. Nei progetti che usano automake è possibile specificarlo all'interno del file Makefile.am principale impostando la variabile ACLOCAL_AMFLAGS:

...
ACLOCAL_AMFLAGS = -I m4
...

Questo viene spesso trascurato dagli sviluppatori originali che semplicemente passano il parametro -I m4 ad aclocal quando compilano i loro pacchetti. Mentre aggiungere una patch per correggere il problema è molto difficile, è invece semplice, se il pacchetto ha una cartella con i file m4 necessari, impostarla nella variabile AT_M4DIR. Lo stesso vale se il pacchetto non usa automake ma solo autoconf.

src_unpack() {
    ...
    AT_M4DIR="m4" eautoreconf
}

Nei rari casi in cui il software usi un sistema di compilazione sostitutivo simile a Cygnus, il precedente esempio può fallire, in quanto prova a cercare la sottocartella m4 dal punto in cui risiede lo script configure; per risolvere questo tipo di problemi, impostare invece la variabile AT_M4DIR a ${S}/m4.

Meno spesso, ma ancora succede, non ci sono cartelle con file m4, o i file con le macro non definite non sono presenti; per risolvere la questione, si deve cercare il pacchetto che fornisce le macro m4, quindi aggiungerlo alla cartella, con una patch o mettendolo su un mirror e poi aggiungendolo a SRC_URI (in questo caso si dovrà aggiungere ${WORKDIR} alla lista delle cartelle di ricerca o posizionarla nella cartella corretta). Questo tipo di problemi è uno dei più fastidiosi, perciò è di solito preferibile informare il prima possibile gli sviluppatori originali così che il rilascio successivo non necessiti di nessun accorgimento.

Discrepanza fra le versioni di automake quando viene eseguito eautoreconf

Talvolta eautoreconf, quando eseguito, fallisce riportando un errore di discrepanza fra le versioni. Ci si potrebbe aspettare di non vedere mai questo errore dal momento che la funzione eautomake si prenderà cura di eseguire nuovamente tutti gli autotools laddove la versione di automake usata per la compilazione del pacchetto differisca da quella usata dall'ebuild; inoltre, durante eautoreconf, gli strumenti sono usati forzando la sostituzione dei file, così che i riferimenti ad automake usati dallo sviluppatore originale dovrebbero sparire del tutto.

L'unica (o almeno la più plausibile) causa è una scarsa conoscenza degli autotools da parte dello sviluppatore dell'ebuild. Quando si trova faccia a faccia col problema descritto in precedenza di possibili macro non definite, lo sviluppatore potrebbe sentirsi costretto a copiare semplicemente il precedente file aclocal.m4 dall'archivio originale con un nome diverso, per preservare anche in questo caso le definizioni delle macro. Sfortunatamente, questo sovrascrive le macro automake, causando questo spesso incomprensibile fallimento.

Fallimenti di automake, richiesta file mancanti

Un altro errore comune, questa volta con automake è un fallimento causato da file mancanti, come NEWS o README. Questo avviene perchè tutti gli autotools assumono, se nessuno li informa del contrario, di stare lavorando in un pacchetto GNU, quindi di avere una serie di file perchè appartenenti alla guida sullo stile di codifica del progetto GNU stesso, e falliscono quando questi file non sono presenti. In questi casi automake dovrebbe essere chiamato col parametro --foreign, che chiede di non fallire se i file richiesti dal progetto GNU non sono presenti.

D'altra parte, la funzione eautomake prova a semplificare la ricompilazione con gli autotools controllando se alcuni dei file del progetto GNU sono presenti, e quindi chiamando automake con le giuste opzioni se non fosse questo il caso. Il modo corretto per risolvere il problema (da notificare agli sviluppatori originali) è aggiungere alla variabile AUTOMAKE_OPTIONS l'opzione foreign così da informarlo di usare il supporto esterno.

Quando i file sono richiesti da configure.in o configure.ac invece che da Makefile.am, e sono di solito i due file config.guess e config.sub, il problema è che il pacchetto non viene correttamente avviato. Per risolvere, automake dovrebbe essere chiamato con l'opzione --add-missing --copy. Questo è quello che la funzione eautomake fa già, così se si riscontra questo problema, dovrebbe essere considerata l'idea di usare le funzioni fornite dall'eclass autotools invece di eseguire i diversi strumenti manualmente o con eventuali script forniti col pacchetto stesso.

Dipendenze di versione mancanti

All'incirca dall'Estate 2006, le funzioni di supporto per automake e autoconf non dipendono forzatamente da tutte le versioni dei rispettivi pacchetti, ciò comporta il non potersi affidare al fatto che gli utenti abbiano tutte le versioni installate, e le dipendenze devono essere risolte in accordo con i pacchetti usati. Per semplificare la gestione delle dipendenze e la forzatura delle versioni necessarie, le variabili WANT_AUTOCONF e WANT_AUTOMAKE sono considerate come input all'eclass che quindi tratterà sia le dipendenze che l'applicativo.

WANT_AUTOCONF="2.1"
WANT_AUTOMAKE="1.4"

inherit autotools

In molti casi, invece di dipendere da una data versione di automake o autoconf, si vorrebbe dipendere dall'ultima versione disponibile, più facilmente già presente nel sistema degli utenti. Per questa ragione, l'eclass autotools accetterà uno speciale valore per le variabili menzionate, latest, che sarà poi espanso in autoconf 2.5 e automake 1.9 o 1.10 in relazione a cosa è smascherato per il dato sistema. Tutto ciò è suggerito quando un pacchetto non deve essere influenzato da qualche caratteristica o malfunzionamento di una vecchia versione di questi.

WANT_AUTOCONF="latest"
WANT_AUTOMAKE="latest"

inherit autotools

Errori nelle fasi di compilazione riguardanti la versione di autoconf

Talvolta potrebbero nascere errori, durante la compilazione di pacchetti, legati alla versione di autoconf, nonostante non siano ricompilati i file degli autotools o in effetti proprio perché non sono stati ricompilati i file degli autotools.

${S}/missing --run
automake-1.10 --gnu  src/Makefile
aclocal.m4:14: error: this file was generated for autoconf 2.61.
You have another version of autoconf.  If you want to use that,
you should regenerate the build system entirely.
aclocal.m4:14: the top level
autom4te-2.62: /usr/bin/m4 failed with exit status: 63
automake-1.10: autoconf failed with exit status: 63
make[2]: *** [Makefile.in] Error 1

Questo messaggio deriva dal codice aggiunto dalla così detta "modalità di manutenzione" fornita da automake. Questa modalità è per lo più intesa per assicurare che gli sviluppatori e gli utenti che compilano manualmente ottengano la versione corretta di configure e Makefile.in, perfino se risultano modificati dopo l'esecuzione di make dist per la creazione dell'archivio.

Mentre la modalità di manutenzione è abbastanza importante sia per gli sviluppatori che per gli utenti che compilano manualmente, essa diventa un fastidio nel cammino degli ebuild poiché esegue automaticamente gli autotools se vengono applicate patch ai file configure.ac o Makefile.am, perfino quando gli autotools non sono compresi nelle dipendenze legate all'atto della compilazione dell'ebuild stesso.

Peggio ancora, se la versione di automake usata dal pacchetto non è installata (per esempio se il pacchetto usa la vecchia versione 1.8, mentre l'utente ha solo la versione 1.10) sarà saltata per intero la fase di ricompilazione, rendendo di fatto il risultato non deterministico dal punto di vista dell'ebuild.

L'errore precedente è causato da un pacchetto che ha uno dei suoi file Makefile.am modificato, di solito tramite una patch, senza che siano stati ricompilati gli autotools. In questi casi, automake sarà invocato solo per ricompilare il Makefile.in coinvolto ma funzionerà solo se la versione di autoconf nel sistema è la stessa di quella usata per creare lo script originale configure. Questo non è il caso una volta che nuove versioni di autoconf sono state rilasciate.

Ciò viene risolto ricompilando gli autotools in modo corretto come descritto in precedenza, attraverso la funzione eautoreconf (o altri metodi dipendenti da eclass eventualmente di livello superiore), invece che lasciando che sia la modalità di manutenzione a preoccuparsi di questo.

Fallimenti durante la configurazione di determinati locales (ad esempio et_EE)

Alcuni pacchetti, usando autoconf 2.13, falliscono nella configurazione di alcuni sistemi con localizzazioni come et_EE. Questo è causato da un bug nella specifica versione di autoconf (risolto nelle versioni successive, le quali non sono retro-compatibili) dove sed tenta di usare una sintassi dipendente dalla localizzazione prima che la variabile LANG sia impostata per usare il locale C (rendendola indipendente dalla localizzazione).

Lo si può osservare per esempio nel bug #103483.

Per risolvere queste situazioni, è possibile applicare la configure-LANG.patch, la quale forza l'impostazione di LANG prima che sia usata la sintassi dipendente dal locale.

Se possibile, viene comunque suggerito di provare ad usare la nuova versione di autoconf (2.59 o successiva) dove il problema è già risolto. Sfortunatamente non è cosa fattibile per tutti i pacchetti, quindi l'applicazione della patch è una buona via per risolvere la questione quando autoconf 2.1 è effettivamente richiesto.

I contenuti di questo documento sono rilasciati sotto la licenza Creative Commons - Attribution / Share Alike.