9.2 `distutils.ccompiler` -- La classe base CCompiler

Questo modulo fornisce la classe di base astratta per la classe CCompiler. Un'istanza CCompiler può essere usata per tutti i passaggi di compilazione e link necessari per compilare un singolo progetto. I metodi vengono forniti per impostare le opzioni del compilatore -- definizioni di macro, include delle directory, percorsi di link, librerie ed il resto.

Questo modulo fornisce le seguenti funzioni:

gen_lib_options( compiler, library_dirs, runtime_library_dirs, libraries): Genera le opzioni di linker per la ricerca delle directory di libreria e di linking con le specifiche librerie. libraries e library_dirs sono, rispettivamente, una lista di nomi di libreria (non i nomi di file!) e le directory di ricerca. Restituisce una lista di opzioni da riga di comando adatta all'uso con alcuni compilatori (in funzione dei due formati di stringa passati).

gen_preprocess_options( macros, include_dirs): Genera le opzioni del pre-processore C (-D, -U, -I) come usato dai due compilatori più comuni: il tipico compilatore Unix e il Visual C++. macros è al solito, una lista di una o doppia tupla, dove (name,) significa non definire (-U), la macro name e (name, value) significa definire (-D), la macro name con value. include_dirs è semplicemente una lista di nomi di directory da aggiungere al percorso di ricerca dei file di intestazione -I. Restituisce una lista di opzioni da riga di comando adatta sia ai compilatori Unix che Visual C++.

get_default_compiler( osname, platform)

Determina il compilatore predefinito da usare per la piattaforma indicata.

osname dovrebbe essere uno dei nomi standard di Python per i vari OS (per esempio uno fra quelli restituiti da os.name e platform, il valore comune restituito da sys.platform per la piattaforma in questione.

Il valore predefinito è os.name e sys.platform nel caso in cui i parametri non vengano indicati.

new_compiler( plat=None, compiler=None, verbose=0, dry_run=0, force=0): Funzione integrata per generare un'istanza di sottoclasse di alcuni CCompiler per la combinazione fornita piattaforma/compilatore. plat assume in modo predefinito os.name (per esempio 'posix', 'nt' e compiler predefiniti sono i predefiniti per quella piattaforma. Attualmente solo 'posix' e 'nt' sono supportati ed i compilatori predefiniti hanno ``l'interfaccia tradizionale Unix`` (classe UnixCCompiler) e visual C++(classe MSVCCompiler). Si noti che è possibile chiedere che un compilatore Unix generi oggetti sotto Windows e che un compilatore Microsoft compili oggetti sotto Unix--se si fornisce un valore per compiler, plat viene ignorato.

show_compilers( ): Stampa una lista di compilatori disponibili (usati dall'opzione --help-compiler di build, build_ext, build_clib).

class CCompiler( [verbose=0, dry_run=0, force=0])

La classe astratta di base CCompiler definisce l'interfaccia che deve essere implementata da una classe compiler reale. La classe ha a disposizione anche alcuni metodi utili usati da diverse classi compiler.

L'idea di base dietro una classe di astrazione del compilatore è che ogni istanza può essere usata per tutti i passaggi di compilazione/link nella preparazione di un singolo progetto. Quindi, attributi comuni a tutti questi passaggi di compilazione e link -- incluse directory, macro da definire, librerie da linkare assieme, etc. -- sono attributi dell'istanza compiler. Per permettere la variabilità nel trattamento individuale di file, molti di questi attributi possono essere variati nella fase di precompilazione o pre-link.

Il costruttore per ogni sottoclasse crea un'istanza dell'oggetto Compiler. Ha a disposizione le seguenti opzioni verbose (mostra un output dettagliato), dry_run (non vengono eseguiti tutti i passaggi) e force (ricompila ogni cosa, indipendentemente dalle dipendenze). Tutte queste opzioni sono, in modo predefinito, impostate a 0 (off). Si noti che probabilmente non si vuole istanziare direttamente CCompiler o una delle sue sottoclassi - si usi piuttosto la funzione integrata distutils.CCompiler.new_compiler().

I seguenti metodi permettono di alterare manualmente le opzioni del compilatore per l'istanza della classe Compiler.

add_include_dir( dir): Aggiunge dir alla lista delle directory in cui verrà effettuata la ricerca per i file di intestazione. Al compilatore viene indicato di cercare nelle directory nell'ordine in cui vengono fornite dalle successive chiamate di add_include_dir().

set_include_dirs( dirs): Imposta la lista delle directory in cui verrà effettuata la ricerca in dirs (una lista di stringhe). Sovrascrive ogni precedente chiamata a add_include_dir(); chiamate successive di add_include_dir() si aggiungono alla lista passata a set_include_dirs(). Questo non influisce su nessuna lista delle directory di include standard in cui il compilatore, per definizione, effettua la ricerca.

add_library( libname)

Aggiunge libname alla lista delle librerie che verranno incluse in tutti i link guidati da questo oggetto compiler. Si noti che libname *non* dovrebbe essere il nome del file contenente la libreria, ma il nome della libreria stessa: il nome del file attuale verrà desunto dal linker, dal compilatore o dalla classe compiler (in funzione della piattaforma).

Il linker verrà istruito a linkare nuovamente le librerie nell'ordine in cui vengono fornite a add_library() e/o set_libraries(). È consentito duplicare i nomi di liberia; il linker verrà istruito a linkare nuovamente le librerie tante volte quante sono quelle menzionate.

set_libraries( libnames): Imposta l'elenco delle librerie da includere in tutti i link guidati dall'oggetto compiler in libnames (una lista di stringhe). Questo non influenza nessuna libreria standard di sistema che il linker deve includere per definizione.

add_library_dir( dir): Aggiunge dir alla lista delle directory in cui devono essere cercate le librerie specificate con add_library(). Il linker verrà istruito a cercare le librerie nell'ordine in cui vengono passate a add_library_dir() e/o set_library_dirs().

set_library_dirs( dirs): Imposta la lista delle directory di ricerca delle librerie a dirs (una lista di stringhe). Questo non influenza nessun percorso di ricerca di libreria standard che il linker deve cercare per definizione.

add_runtime_library_dir( dir): Aggiunge dir alla lista di directory in cui si devono cercare le librerie condivise durante l'esecuzione.

set_runtime_library_dirs( dirs): Imposta la lista delle directory di ricerca per le librerie condivise durante l'esecuzione a dirs (una lista di stringhe). Questo non influenza ogni percorso di ricerca standard che il linker durante l'esecuzione deve cercare per definizione.

define_macro( name[, value=None]): Definisce una macro di preprocessore per tutte le compilazioni guidate da questo oggetto compiler. Il parametro facoltativo value dovrebbe essere una stringa; se non viene indicato, la macro verrà definita senza un valore esplicito e l'esatto risultato dipende dal compilatore usato (XXX vero? ANSI dice qualcosa circa questo argomento?)

undefine_macro( name): Non definisce una macro di preprocessore per tutte le compilazioni guidate dall'oggetto compiler. Se la stessa macro viene definita da define_macro() e non definita da undefine_macro() l'ultima chiamata assume la precedenza (include ridefinizioni multiple o non definizioni). Se la macro viene ridefinita/non-definita sulla base di precompilazioni (per esempio nella chiamata a compile()), poi ne assume la precedenza.

add_link_object( object): Aggiunge object alla lista degli oggetti file (o analoghi, come un file di libreria espressamente indicato o il risultato di ``compilatori di risorse'') da includere in ogni link guidato da questo oggetto compiler.

set_link_objects( objects): Imposta la lista degli oggetti file (o analoghi) che devono essere inclusi in ogni link ad objects. Questo non influisce sugli oggetti file standard che il linker deve includere per definizione (come le librerie di sistema).

I seguenti metodi implementano metodi per l'auto individuazione delle opzioni del compilatore, fornendo alcune funzionalità simili all'autoconf della GNU.

detect_language( sources): Individua il linguaggio di un file indicato, o di una lista di file. Usa l'attributo di istanza language_map (un dizionario) e language_order (una lista) per fare il lavoro richiesto.

find_library_file( dirs, lib[, debug=0]): Effettua una ricerca nella specifica lista di directory per un file condiviso o statico lib e restituisce il percorso completo di quel file. Se debug è vera, cerca per una versione di debugging (se ha senso sulla piattaforma corrente). Restituisce None se lib non viene trovata in nessuna delle directory specificate.

has_function( funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None]): Restituisce un valore booleano che indica se funcname viene supportato sulla piattaforma corrente. Gli argomenti facoltativi possono essere usati per implementare l'ambiente di compilazione fornendo file e directory di intestazioni addizionali e file o percorsi di libreria.

library_dir_option( dir): Restituisce le opzioni del compilatore per aggiungere dir alla lista delle directory di ricerca delle librerie.

library_option( lib): Restituisce le opzioni del compilatore per aggiungere dir alla lista delle librerie linkate in librerie condivise o nell'eseguibile.

runtime_library_dir_option( dir): Restituisce l'opzione del compilatore per aggiungere dir alla lista delle directory dove vengono cercate le librerie di runtime.

set_executables( **args)

Definisce gli eseguibili (e le loro opzioni) che verranno eseguiti nei diversi stadi della compilazione. L'esatto insieme di eseguibili che devono essere eseguiti possono essere qui specificati, in funzione pure della classe compiler (attraverso l'attributo di classe 'executables') ma comunque devono avere:

attributo descrizione

compiler Il compilatore C/C++
linker_so linker usato per creare oggetti e librerie condivise
linker_exe linker usato per creare binari eseguibili
archiver creatore di libreria statico

attributo	descrizione
compiler	Il compilatore C/C++
linker_so	linker usato per creare oggetti e librerie condivise
linker_exe	linker usato per creare binari eseguibili
archiver	creatore di libreria statico

Sulle piattaforme con una riga di comando (Unix, DOS/Windows), ognuna di queste è una stringa che verrà suddivisa nel nome dell'eseguibile e (facoltativamente) una lista di argomenti. La suddivisione della stringa viene effettuata in modo similare a come la shell Unix lavora: le parole vengono delimitate da spazi, ma virgolette e backslash possono sovrascriverle. Si veda distutils.util.split_quoted().

I seguenti metodi invocano le diverse fasi del processo di compilazione.

compile( sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])

Compila uno o più file sorgenti. Genera l'oggetto file (per esempio trasforma un file .c in un file .o).

sources deve essere una lista di nomi di file, più esattamente file C/C++, ma in realtà ogni cosa che può essere gestita da un particolare compilatore e da una particolare classe Compiler (per esempio la MSVCCompiler può gestire file di risorse in sources). Restituisce una lista di nomi di oggetti file, uno per ogni nome di file sorgente presente in sources. A seconda dell'implementazione, non tutti i file sorgenti verranno necessariamente compilati, ma tutti i corrispondenti nomi di oggetti file verranno restituiti.

Se output_dir viene indicata, gli oggetti file vi saranno inseriti, mantenendo comunque il loro componente relativo al percorso originale. Quindi foo/bar.c normalmente si compila in foo/bar.o (per una implementazione Unix); se output_dir è build, verrà quindi compilato in build/foo/bar.o.

macros, se indicata, deve essere una lista di definizioni di macro. Una definizione di macro è sia una tupla-doppia (name, value) che singola (name,). Il primo definisce una macro; se il valore è None, la macro viene definita senza un esplicito valore. Il caso della singola tupla non-definisce una macro. Successive definizioni/ridefinizioni/non-definizioni acquisiscono la precedenza.

include_dirs, se indicato, deve essere una lista di stringhe, le directory da aggiungere ai percorsi di ricerca standard per gli include, solamente in questa compilazione.

debug è booleano; se vero, il compilatore verrà informato di fornire in uscita i simboli di debug nell'oggetto/i file.

extra_preargs e extra_postargs sono implementazioni dipendenti. Sulle piattaforme che possiedono la notazione da riga di comando (per esempio Unix, DOS/Windows), sono più semplicemente liste di stringhe: argomenti da riga di comando extra da aggiungere alla riga di comando del compilatore. Per le altre piattaforme, si consulti la documentazione dell'implementazione della classe. In ogni caso, vengono intese come una scappatoia per quelle occasioni in cui l'ambiente astratto del compilatore non rispetta le aspettative.

depends, se indicato, è una lista di nomi di file da cui tutti gli obiettivi dipendono. Se un file sorgente è più vecchio di ogni file nelle dipendenze, il file sorgente non verrà ricompilato. Questo supporta il tracciamento delle dipendenze, ma solo ad un livello di granularità grossolana.

Solleva l'eccezione CompileError in caso di fallimento.

create_static_lib( objects, output_libname[, output_dir=None, debug=0, target_lang=None])

Effettua il link dei diversi pezzi, ``bunch of stuff'', per creare un file di libreria statico. Il concetto di ``bunch of stuff'' si compone di una lista di oggetti file forniti come objects, oggetto file supplementare fornito ad add_link_object() e/o set_link_objects() e le librerie fornite da add_library() e/o set_library(), ed infine, se presenti, le librerie fornite come libraries.

output_libname dovrebbe essere un nome di libreria, non un nome di file; il nome del file verrà dedotto dal nome della libreria. output_dir è la directory dove il file di libreria verrà inserito.

debug è un tipo booleano; se vero, le informazioni di debugging verranno incluse nella libreria (si noti che su diverse piattaforme, è nel passaggio della compilazione che questo avviene: l'opzione debug qui viene inclusa solamente per coerenza).

target_lang è il linguaggio di destinazione per cui l'oggetto indicato viene compilato. Questo permette uno specifico trattamento durante la fase di linking per alcuni linguaggi.

Solleva l'eccezione LibError in caso di errore.

link( target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

Linka un ``bunch of stuff'' assieme per creare un eseguibile o una libreria condivisa.

Il concetto di ``bunch of stuff'' è composto da una lista di oggetti file forniti come objects. output_filename dovrebbe essere un nome di file. Se output_dir viene fornito, output_filename è a lui relativo (per esempio output_filename può fornire componenti di directory se necessario).

libraries è una lista di librerie da linkare assieme. Queste sono nomi di librerie, non nomi di file, dal momento che questi vengono tradotti in nomi di file nella modalità specifica della piattaforma (per esempio foo diventa libfoo.a in Unix e foo.lib in DOS/Windows). Comunque, possono includere un componente di directory, che dice al linker di cercare in quella specifica directory anziché cercare in tutti i soliti posti.

library_dirs, se indicate, dovrebbero essere una lista di directory dove cercare le librerie che sono state specificate come nomi di libreria semplice (per esempio nessun componente di directory). Queste si trovano all'inizio del sistema predefinito e forniscono quanto richiesto a add_library_dir() e/o set_library_dirs(). runtime_library_dirs è una lista di directory che verranno inserite all'interno della libreria condivisa ed usate per cercare altre librerie condivise da cui *queste* dipendono durante l'esecuzione. (Questo è rilevante solo su Unix).

export_symbols è una lista di simboli che le librerie condivise esporteranno. (Questo è rilevante solo su Windows.)

debug è come per compile() e create_static_lib(), con una piccola distinzione che attualmente riguarda la maggior parte delle piattaforme (al contrario di create3_static_lib(), che include un'opzione debug principalmente per la propria configurazione).

extra_preargs e extra_postargs sono come per compile() (eccetto per il fatto che abitualmente forniscono argomenti da riga di comando per il particolare linker da usare).

target_lang è il linguaggio di destinazione per cui l'oggetto indicato viene compilato. Questo permette un trattamento specifico durante il linking per particolari linguaggi.

Solleva l'eccezione LinkError in caso di errore.

link_executable( objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None]): Effettua il linking nell'eseguibile. output_progname è il nome del file eseguibile, quando objects è una lista di nomi di oggetti file da linkare. Altri argomenti sono gli stessi del metodo link.

link_shared_lib( objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]): Effettua il link di una libreria condivisa. output_libname è il nome della libreria risultante, quando objects è una lista di nomi di oggetti file da linkare. Altri argomenti sono gli stessi del metodo link.

link_shared_object( objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]): Linka un oggetto condiviso. output_filename è il nome dell'oggetto condiviso che verrà creato, mentre objects è una lista di nomi di oggetti file da linkare. Altri argomenti sono gli stessi del metodo link.

preprocess( source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None]): Preprocessa un singolo file sorgente C/C++, indicato in source. Il risultato verrà scritto nel file chiamato output_file, o stdout se output_file non viene fornito. macros è una lista di definizioni macro, come per compile(), che incrementerà l'insieme delle macro con define_macro() e undefine_macro(). include_dirs è una lista di nomi di directory che verranno aggiunte alla lista predefinita, alla stregua di add_include_dir().
Solleva l'eccezione PreprocessError in caso di errore.

I seguenti comodi metodi vengono definiti dalla classe CCompiler, per essere usati da diverse concrete sottoclassi.

executable_filename( basename[, strip_dir=0, output_dir='']): Restituisce il nome del file dell'eseguibile per il basename indicato. Tipicamente per piattaforme non-Windows il nome è il medesimo di basename, mentre in Windows si otterrà l'aggiunta di .exe.

library_filename( libname[, lib_type='static', strip_dir=0, output_dir='']): Restituisce il nome del file per il nome della libreria indicata sulla piattaforma corrente. In Unix una libreria con lib_type di tipo 'static' tipicamente sarà nella forma di liblibname.a, quando con lib_type di tipo 'dynamic' sarà nella forma di liblibname.so.

object_filenames( source_filenames[, strip_dir=0, output_dir='']): Restituisce il nome degli oggetti file per i file sorgenti indicati. source_filenames dovrebbe essere una lista di nomi di file.

shared_object_filename( basename[, strip_dir=0, output_dir='']): Restituisce il nome di un oggetto file condiviso per il nome di file indicato da basename.

execute( func, args[, msg=None, level=1]): Invoca distutils.util.execute(). Questo metodo invoca una funzione Python func con gli argomenti indicati args, dopo aver registrato ed inserito nell'account l'opzione dry_run. XXX si veda anche....

spawn( cmd): Invoca distutils.util.spawn(). Questa invoca un processo esterno da eseguire per il comando indicato. XXX si veda anche...

mkpath( name[, mode=511]): Invoca distutils.dir_util.mkpath(). Questa crea una directory e qualsiasi directory collegata mancante. XXX si veda anche...

move_file( src, dst): Invoca distutils.file_util.move_file(). Rinomina src in dst. XXX si veda anche...

announce( msg[, level=1]): Scrive un messaggio usando distutils.log.debug(). XXX si veda anche...

warn( msg): Scrive un messaggio di avvertimento msg su standard_error.

debug_print( msg): Se l'opzione debug viene impostata in questa istanza di CCompiler, stampa msg su standard output, altrimenti non fa nulla.

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.

9.2 distutils.ccompiler -- La classe base CCompiler

9.2 `distutils.ccompiler` -- La classe base CCompiler