
Costruire pacchetti per "Bad Penguin"
@1998,99,2000 by Antonio GALLO <agx@TOGLIMI.linux.it>
========================================================
1999-06-10, Versione 1.0.0 (2^ revisione) by AGX
1999-08-17, Versione 1.1.0 by AGX
1999-08-30, Versione 1.2.0 by AGX: CANDIDATE
1999-09-14, Versione 1.2.2 by AGX: OFFICIAL
1999-12-13, Versione 1.6.2 by AGX: package-builder 1.6.2
--------------------------------------------------------




0. Introduzione
===============

Questo documento spiega, attraverso l'uso dello script "package-builder"
i passi e le POLICY da rispettare, per la costruzione di un pacchetto
in formato Bad Penguin.

Lo script "package-builder" e' un vero "coltellino svizzero" nel lavoro
di mantaining di un pacchetto. Esso automatizza il 90% delle operazioni
e lascia al mantainer la sola fase di revisione e controllo della corretta
esecuzione delle operazioni.

Ecco le specifiche ....

... prima di proseguire e' necessario modificare, all'interno dello script,
le variabili: DVERSION, PVERSION, PKG_SPOOL, DIST_DIR


1. Invocazione del programma
============================

Se il programma viene invocato senza nessun parametro oppure 
specificando "--help" o -"h" viene visualizzato l'help a video
che offre una visione delle vari possibili comandi.

I comandi sono descritti secondo l'ordine da seguire per completare
il processo di pacchettizzazione.

Il primo parametro da passare a package-builder e' il comando
mentre il secondo e' la directory da utilizzare per costruire il
pacchetto. Si consiglia formtemente di lasciare il secondo parametro
vuoto in modo tale da lasciare allo script l'utilizzo del valore di
default "/pkg-build"



2. Preparazione del source
==========================

E' fortemente suggerito di effettuare tutte le operazioni
come "root", in quanto c'e' bisogno di avere anche i permessi
per disinstallare e reinstallare il programma.

Si consiglia di decomprimere il source all'interno della propria
home directory e di portarsi all'interno della directory del
programma da compilare per eseguire tutte le oGREEN "Applying permissions to incoming (press ENTER at the end)..."
	  OLD_DIR=$PWD
	  cd $PKG_DIR/incoming
	  echo | sh permissions.sh 2>/dev/null
	  cd $OLD_DIR
	  echNFO




3. Inizializzazione (--create)
==============================

Lanciare il comando
	package-builder  --create

Questo provvede a creare la directory
	/pkg-build
	/pkg-build/install
ed a toccare il file
	/pkg-build/install/MILESTONE
che viene usato per il controllo dei file installati.

Inoltre vi vengono chieste precise informazioni sul pacchetto,
quali:
    - il nome del pacchetto, SONAME
    - la categoria di appartenenza, CATEGORY
    - il numbero di versione, VERSION



4. Configurazione (--configure)
===============================

Lanciando il comando
	package-builder  --configure

Lo script controlla se e' presente lo script "configure" nella home
del programma e se e' stato gia' generato un Makefile, questo ci assicura
che il programma sia stato sviluppato usando i tools della GNU Autoconf
ed Automake. In caso contrario dovremmo provvedere manualmente alla
configurazione e compilazione del programma e quindi saltare allo step
per il controllo dei file installati (--rescan).

Quindi viene chiesto se e' stata letta tutta la documentazione.

In caso negativo lo script vi permette di leggere tutti i documenti
presenti, di solito quelli che iniziano con una lettera maiuscola,
nonche' il risultato del comando "./configure --help" che vi da
informazioni sui comandi accettati dallo script.

Letta la documentazione, lo script provvede a generare lo script
/pkg-build/install/COMPILE che conterra i comandi per compilare
nella maniera piu' ottimizzata possibile il vostro sorgente,
ovviamente vi viene chiesto di modificarlo.

Al termine dell'operazione viene lanciato
	make distclean
che ripulisce TUTTO il source riportandolo alla situazione originale
e quindi viene configurato il source lanciando lo script COMPILE.





5. Note sull'ottimizzazione
===========================



Ottimizzazioni di default
--------------------------
Bad Penguin attualmente fornisce il compilatore egcs 1.0.3
per questo compilatore utilizziamo i seguenti flag:
	CFLAGS="-O6 -mpentium -malign-loops=2 -malign-jumps=2 -malign-functions=2"

Nel caso si usasse il nuovo gcc, si puo utilizzare:
	CFLAGS="-O3 -m486 -malign-loops=2 -malign-jumps=2 -malign-functions=2"

mentre nel caso del gcc 2.7.2.1 e precedenti:
	CFLAGS="-O2 -fno-strength-reduce"

NOTA: L'opzione "-mpentium" e sinonima di "-mcpu=i586"



Compilare altre librerie
------------------------
Per alcune vecchie librerie SHARED potrebbe essere necessario
aggiungere i seguente flag alla variabile CFLAGS
	CFLAGS= -fPIC  

E per abilitare il supporto ai thread aggiungere
	CFLAGS= -D_REENTRANT
	LDFLAGS= -lpthread



Compilare la Lib C
-------------------
Per la compilazione della libc e' fortemente consigliato utilizzare
questi parametri invece di quelli forniti di default.

	CFLAGS=O3  ./configure  \
		--enable-add-ons=crypt,linuxthreads,localedata \
		--enable-omitfp --prefix=/usr --with-gnu-ld \
		--with-gnu-as --disable-profile




6. Compilazione del programma (--build)
=======================================

Questa fase e' una delle piu' semplici,
una volta lanciato lo script
	package-builder  --build

viene compilato il programma lanciando
	make
e quindi controllato il risultato con
	make check





7. Scannin (--scan) e Rescanning (--rescan)
===========================================

Uno dei problemi piu' grandi e' riuscire a capire quali file sono stati
installati dal programma. Per far cio' e' richiesta :
    - esperienza
    - competenza
non si puo' "arrangiare" questa fase.


Dopo aver compilato il programma e' necessario capire quali file sono stati
installati. Per far cio' si lancia il comando
	package-builder --scan

Lo script esegue la seguente sequenza di comandi,
	- make uninstall, per disinstallare una precedente installazione del programma
	- make build, per assicurarsi che non ci sia nulla da ricompilare
	- make install, per installare il programma nuovamente
quindi lancia "ldconfig" effettua il "sync" ed attende 5 secondi ...

Dopodiche' una serie di find vanno a cercare i file creati o modificati
da quando e' stato toccato il file di MILESTONE, questo comporta che
vengono inclusi anche files che non fanno parte del programma.

Per ovviare a cio' il programma apre un editor con i risultati ottenuti
che possono essere modificati, alla fine la lista dei file viene copiata
all'interno del ramo pkg-build dove verra' assemblato il pacchetto.





8. Controllo del pacchetto (--check)
====================================

Questa e' una delle fasi piu' importanti. Mediante il comando
	package-builder  --check
vengono applicate e controllate alcune importanti policy del pacchetto.

In pratica ...



Documentazione del pacchetto
----------------------------
Tutti i file piu' importanti ( README, INSTALL, COPYING ) vanno nella
directory /usr/doc/$NOMEPACCHETTO in forma compressa e con mode=644

Non vanno compressi i file HTML e le immagini GIF (.gif), JPEG (.jpg)
e PNG (.png)



Documentazione in formato info
------------------------------
Va installata in /usr/info, compressa e con mode=644

Viene controllato che nei file POST-INSTALL e PRE-REMOVE venga richiamato
il file install-info.


In futuro (...TODO...) andrebbe automaticamente aggiungo la 
seguente sequenza di comandi per l'installazione e la rimozione:

Per l'installazione delle pagine va aggiunto in POST-INSTALL
	install-info --quiet --section "Section Name"  /usr/info/foobar.info.gz  /usr/info/dir

ed in PRE-REMOVE:
	install-info  --quiet  --delete /usr/info/nomefile.info.gz  /usr/info/dir
(...TODO... la rimozione sembra non funzionare se il file e' compresso)



Pagine di manuale
-------------------------------
Memorizzate in /usr/man in forma compressa e con mode=644



Stripping
-------------------------------
Tutti i binari e tutte le librerie devono essere strippati con
	strip  --strip-unneeded  <nome_file>


Dipendenze per gli Script
-------------------------------
Se il pacchetto fa uso di script di shell (bourne) o perl
vengono aggiunte le relative dipendenze.


Script di installazione
-------------------------------
Tutti gli script di installazione vengono settati a mode=755 ed owner=root.root
inoltre viene controllato che al loro interno vi sia "set -e" e che NON venga
usato "set -x"


Controllo icona
-------------------------------
Tutti i programmi devono avere un icona "Gnome" (che viene usata anche da KDE)
in /usr/share/apps/$SOTTOCARTELLA/

Il file "$NOME_APPLICAZIONE.desktop" cosi' costituito:

    [Desktop Entry]
    Name=Electric Eyes
    Name[es]=Ojos Elctricos
    Name[it]=Occhio Elettrico
    Comment=Image display program
    Comment[it]=Meraviglioso programma di visualizzazione immagini
    Exec=ee
    Icon=gnome-ee.png
    Terminal=0
    Type=Application


Controllo dei nomi di libreria
-------------------------------
(Questo paragrafo deriva dal LSB - Linux Standard Base)

Per ogni libreria shared ci devono essere tre referenze:
	- la libreria stessa:	lib<name>.so.X.Y.Z
	- il link di runtime:	lib<name>.so.X
	- il link di sviluppo:	lib<name>.so

Unica eccezione la glib C che ha la seguente forma per la libreria
condivisa:
	- lib<name>-X.Y.Z.so

Se la libreria condivisa e' ormai una vecchia versione e si desidera
fornire un link di sviluppo, esso puo' essere della seguente forma:
	- lib<name>X.so


Chiavi MD5
----------
Viene generato il file MD5SUM con tutte le chiavi MD5 degli eseguibili



Permissions
-------------------------------
Al termine dell'operazione, sulla directory /pkg-build, vengono applicati
i permessi utilizzando lo script "permissions.sh"





9. ANALISI DELLE DIPENDENZE (--request)
=======================================

Il comando
	package-builder  --request
effettua l'analisi delle dipendenze.


Viene eseguito il comando ldd su tutti i file del pacchetto
per recupare l'elenco delle librerie usate. L'elenco dopo
essere stato opportunamente elaborato viene verificato riga
per riga in modo da trovare in /var/spool/agxpackages/*
quali pacchetti forniscono la libreria specificata :-)

Il risultato viene posto direttamente in /pkg-build/install/REQUEST
che viene automaticamente aperto con un editor per la modifica.


CONFLICTS
---------
Dopo le dipendenze viene richiesto di editare il file CONFLICTS contenente
le maschere dei pacchetti in conflitto con quello attuale.



10. Preparazione del pacchetto (--prepare)
==========================================

Il comando
    package-builder --prepare
effettua il building del pacchetto, cioe' la compressione.

Prima di essere compresso vengono richieste altre informazioni
sul pacchetto:
	- l'architettura del pacchetto (ARCH) e quella per cui e' stato
	  ottimizzato (OPTIM)
	- un breve sommario di cos'e' il pacchetto (SUMMARY)
	- il DISKNAME
	- lo STATUS
	- l'autore del software (AUTHOR)
	- il tipo di copyright: GPL, BSD, etc. (COPYRIGHT)
	- la descrizione completa del pacchetto (DESCRIPTION)
	- l'e-mail del mantainer (MANTAINER)
	- l'URL del pacchetto (URL)
	- il sito FTP da dove si e' scaricato o comunque la fonte utilizzata (FTPURL)

Ed automaticamente:
	- DISKUSAGE all 'du' della directory /pkg-build
	- BUILDTIME viene posto alla data-ora attuale
	- MANIFEST con tutti i nomi dei file presenti nel pacchetto.
	- DISTRIBUTION, BUILDHOST, BPPVERSION

Indi il pacchetto viene compresso utilizzando il SONAME ed il numero
di versione specificati all'inizio.





11. Ufficializzazione (--announce)
==================================
Il lancio del comando
	package-builder --announce
provvede a
	- spostare nella categoria "z-removed" tutti i pacchetti nella
	  distribuzione in conflitto con quello attuale
	- copiare il pacchetto nell'alberatura della distribuzione



12. Autobuild (--autobuild)
===========================
Lanciando
    package-builder --autobuild
vengono eseguiti tutti gli step automaticamente e sequenzialemente.
In caso di problemi il parametro --autobuild prosegue l'esecuzione
sempre dall'ultimo step ultimato con successo.

