PLD-doc: devel-hints-pl.txt - synced structure with -en
pawelz
pawelz at pld-linux.org
Thu Jun 10 14:53:42 CEST 2010
Author: pawelz Date: Thu Jun 10 12:53:42 2010 GMT
Module: PLD-doc Tag: HEAD
---- Log message:
- synced structure with -en
---- Files affected:
PLD-doc:
devel-hints-pl.txt (1.66 -> 1.67)
---- Diffs:
================================================================
Index: PLD-doc/devel-hints-pl.txt
diff -u PLD-doc/devel-hints-pl.txt:1.66 PLD-doc/devel-hints-pl.txt:1.67
--- PLD-doc/devel-hints-pl.txt:1.66 Mon Jun 7 16:53:53 2010
+++ PLD-doc/devel-hints-pl.txt Thu Jun 10 14:53:37 2010
@@ -6,11 +6,12 @@
rozbieżność między wersją angielską i polską, popraw, albo przynajmniej
wyraźnie oznacz odpowiednie miejsce.
-TODO:
- przenieść strukturę devel-hints-en.txt. Docelowo poszczególne fragmenty obu
- dokumentów powinny mieć takie same numery sekcji. Ułatwi to równoległe
- utrzymywanie dwóch wersji językowych dokumentu.
+ Poszczególne fragmenty obu dokumentów mają takie same numery sekcji. Ułatwi
+ to równoległe utrzymywanie dwóch wersji językowych dokumentu. Proszę o
+ przestrzeganie tej zasady.
+TODO:
+ przenieść strukturę devel-hints-en.txt.
Wskazówki dla deweloperów PLD
@@ -20,6 +21,7 @@
są przeznaczone między innymi do omawiania dokonanych zmian w repozytorium
i dyskutowania zmian planowanych.
+1. Ogólne zasady
Dodając speca nie bazującego na template*.spec należy go potraktować
skryptem adapter.awk (więcej o używaniu tego skryptu można znaleźć (po
@@ -31,9 +33,22 @@
(np. pl_PL.UTF-8 lub en_GB.UTF-8), aby poprawnie rozpoznał długość
linii.
+1.2. Środowisko budowy pakietów
+
Pakiet musi się budować z konta zwykłego użytkownika bez dodatkowych
kombinacji.
+1.3. Kodowanie
+
+Pliki .spec (podobnie jak pliki .desktop) obecnie są kodowane w UTF-8, więc
+w tym kodowaniu muszą być zlokalizowane opisy (w tym polskie, oznaczone
+lokalizacją pl_PL.UTF-8). Jedynie główne opisy (Summary:, %description bez
+-l) powinny być utrzymywane w czystym ASCII (można natomiast dodać opisy
+z lokalizacją en_GB.UTF-8 lub en_US.UTF-8 ze znakami spoza ASCII).
+
+1.4. Sekcja %description
+
+Zawartość sekcji "description" należy formatować na 70 znaków.
Polskie opisy powinny być w języku polskim.
W szczególności dotyczy to ortografii, stosowania znaków diakrytycznych
@@ -49,15 +64,8 @@
- nazwy typu "Hortex", "Pewex" odmieniamy -ex, -eksu, -eksem, -ksie
itd. (czyli np. Blackboksa, Postfiksa)
-Pliki .spec (podobnie jak pliki .desktop) obecnie są kodowane w UTF-8, więc
-w tym kodowaniu muszą być zlokalizowane opisy (w tym polskie, oznaczone
-lokalizacją pl_PL.UTF-8). Jedynie główne opisy (Summary:, %description bez
--l) powinny być utrzymywane w czystym ASCII (można natomiast dodać opisy
-z lokalizacją en_GB.UTF-8 lub en_US.UTF-8 ze znakami spoza ASCII).
-
-Zawartość sekcji "description" należy formatować na 70 znaków.
+2. Nazwy pakietów:
-Nazwy pakietów:
W przypadku niektórych klas pakietów stosujemy ujednolicone nazewnictwo.
W szczególności:
- dla modułów Apache'a 2.x: apache-mod_<nazwa>
@@ -68,7 +76,11 @@
- dla modułów binarnych PECL, będących rozszerzeniami PHP: php-pecl-nazwa
- dla modułów jądra: kernel-typ-nazwa (typ jest taki sam, jak podkatalog
w drivers/ w którym znalazłby się moduł - np. char, net itd.)
-- dla nienatywnych bibliotek: <język>-<nazwa>, na przykład:
+
+2.1. Nienatywne biblioteki (perl, java, etc)
+
+Nienatywne biblioteki powinny być nazywane według schematu <język>-<nazwa>.
+Przykłady:
* dla modułów Perla: perl-nazwa (dla modułów obiektowych zazwyczaj
nazwa jest postaci Klasa[-Klasa[-Klasa...]]
* dla modułów Pythona: python-<nazwa>
@@ -84,6 +96,8 @@
użyj flagi -n aby utworzyć podpakiet bez prefiksu <nazwa>). Aby obejrzeć
przykład takiego pakietu zobacz ack.spec.
+2.2. Natywne biblioteki
+
Podział na podpakiety:
Pakiety zawierające biblioteki dzielone standardowo dzielimy na:
podstawowy (zawierający pliki m.in. lib*.so.*.*, podstawową dokumentację
@@ -101,7 +115,14 @@
się w pakiecie podstawowym i _są_ konieczne do pracy aplikacji - wtedy
należy _koniecznie_ zaznaczyć komentarzem ten fakt w specu.
-Wersje pakietów:
+3. Wersje pakietów:
+
+3.1. Tag Release
+
+TODO - przetłumaczyć z en
+
+3.2. Wersja aplikacji a tagi Version i Release
+
Dla pełnych wydań pole Version zawiera wersję pakietu.
Dla wersji rozwojowych lub testowych (snapshotów z CVS, wszelkich alpha,
beta, gamma, pre, rc), aby uniknąć ciągłego podbijania Epoch, w polu
@@ -110,16 +131,22 @@
rc2 i beta będą to 0.rc2.1, dla snapshotów ciąg typu 0.20030303.1).
Przykładowy opis w specu (wersja rzeczywista: 2.0rc1)
Version: 2.0
-%define rcver rc1
-Release: 0.%{rcver}.1
+%define rel 1
+%define subver rc1
+Release: 0.%{subver}.%{rel}
W takim przypadku po zmianach speca dla tej samej wersji oprogramowania
zwiększamy ostatnią liczbę w Release ("0" pozostaje bez zmian!).
+3.3 Tag Epoch
+
+TODO - przetłumaczyć z en
+
+4. Tag Group
-Grupy pakietów:
Pakiet musi posiadać zdefiniowane pole Group: zgodnie z packages/rpm.groups
+5. Paczkowanie zewnętrznych modułów jądra
Nie umieszczamy "BuildRequires: kernel-headers" w pakietach z samymi
programami user-space (sam pakiet glibc-devel wymaga właściwych
@@ -135,6 +162,9 @@
%{?with_dist_kernel:%requires_releq_kernel_smp}
(dla modułów jądra SMP)
+6. autotools
+
+6.1. BuildRequires
Dodając wywołania narzędzi auto* i *ize należy pamiętać o dopisywaniu
zależności:
@@ -166,6 +196,8 @@
makro AC_CONFIG_AUX_DIR, to wersja >= 1:1.4.3 (lub 2:1.4e
w przypadku bibliotek w C++)
+6.2. Używanie autotools w specu
+
O ile to możliwe, programy te uruchamiamy używając makr (dla informacji
z prawej podane są rozwinięcia tych makr):
@@ -217,8 +249,7 @@
Oczywiście należy wtedy dodać BuildRequires: automake.
-
-Zależności przy budowaniu pakietów:
+7. Zależności przy budowaniu pakietów:
Wszystkie pakiety potrzebne do zbudowania danego pakietu P (oprócz
nagłówków jądra) powinny być wymagane jawnie - w jednym z trzech miejsc:
@@ -263,6 +294,8 @@
w przypadku gdy pakiet zmienia nazwę lub w innych dystrybucjach występuje
pod inną nazwą.
+8. Makro %_sysconfdir
+
Nie używamy makra %{_sysconfdir} w ścieżkach do stałych,
ogólnosystemowych katalogów:
/etc/cron.*
@@ -275,7 +308,8 @@
/etc/skel
/etc/sysconfig
-Sekcja przygotowania źródeł (%prep)
+9. Sekcja przygotowania źródeł (%prep)
+
W tej sekcji następuje przygotowanie źródeł do procesu budowania poprzez
rozkompresowanie źródeł, nałożenie łatek itp.
W najprostszym przypadku sekcja ta wygląda:
@@ -327,7 +361,8 @@
Pamiętaj, żeby dodać odpowiednie BR-y dla makra %undos takie, jak opisano w
pliku BuildRequires.txt.
-Sekcja budowania (%build):
+10. Sekcja budowania (%build):
+
W tej sekcji należy zawrzeć wszystko co spowoduje zbudowanie pakietu w
katalogu %{_topdir}/BUILD w drzewie budowania rpma. W sekcji tej katalog
$RPM_BUILD_ROOT nie powinien być używany.
@@ -354,10 +389,12 @@
nalezy zmienić -lqt na -lqt-mt (używając opcji configure, zmiennej
środowiskowej, łaty lub seda).
-Sekcja instalacji (%install):
+11. Sekcja instalacji (%install):
+
Służy do zawarcia komend instalujących to co zostało wybudowane w sekcji
budowania w katalogu $RPM_BUILD_ROOT. Powinna się rozpoczynać od
wyczyszczenia owego katalogu:
+
%install
rm -rf $RPM_BUILD_ROOT
@@ -368,6 +405,7 @@
użyć %{name}, niektóre pakiety używają różnej nazwy). Jeśli w pakiecie
są pliki *.mo o różnych nazwach i wszystkie mają się znaleźć w tym samym
pakiecie, to można użyć makra w postaci:
+
%find_lang %{name} --all-name
Dodatkowo makro %find_lang może obsłużyć tłumaczenia pomocy z GNOME
@@ -395,7 +433,10 @@
(tworzenia samego pakietu) można osiągnąć ustawiając makro %_binary_payload
na w1.gzdio.
-Lista plików (%files):
+12. Lista plików (%files):
+
+12.1. Katalogi
+
Kompletując listę plików nie można zapominać o katalogach. Każdy katalog
powinien należeć do dokładnie jednego pakietu spośród tych, które można
zainstalować naraz. Katalog nie należący do żadnego pakietu jest błędem -
@@ -416,6 +457,8 @@
Jeśli gdzieś występuje użycie applnkdir - usuwamy jako obsolete.
+12.2. Konfliktujące pliki
+
Czasem przez pomyłkę jeden plik znajduje się w kilku pakietach które
powinny dać się zainstalować równocześnie.
poldek nie poinformuje o szczegółach podczas instalacji i konflikt trzeba
@@ -424,6 +467,8 @@
poldka: poldek -V --verify-fileconflicts -v (który wykryje także włączenie
kopii tego samego pliku lub katalogu do różnych pakietów).
+12.3. Specjalne atrybuty
+
Należy też pamiętać o specjalnych atrybutach dla plików specjalnych
takich jak:
Pliki konfiguracyjne (które nie powinny być podmieniane o ile były
@@ -440,7 +485,8 @@
należy je utworzyć w skrypcie %post pamiętając o nadaniu im odpowiednich
uprawnień.
-Sekcja %files dla bibliotek dzielonych:
+12.4. Sekcja %files dla bibliotek dzielonych
+
Przypuśćmy, że mamy bibliotekę example w wersji 1.0.2, której SONAME to
libexample.so.1. Wtedy sekcje %files powinny wyglądać tak:
@@ -463,7 +509,8 @@
zastepujemy numeru wersji wildcardem '?'. Dzięki temu napewno zauważymy zmianę
SONAME przy podbijaniu pakietu do nowszej wersji.
-Pliki *.desktop.
+12.5. Pliki *.desktop
+
Główne pliki *.desktop aplikacji ląduja zawsze w:
%{_desktopdir}
(dla aplikacji KDE w %{_desktopdir}/kde )
@@ -485,7 +532,8 @@
Dokładniejsze informacje o ich zawartości uzyskamy pod adresem
http://www.freedesktop.org/standards/desktop-entry-spec/
-Dokumentacja (pliki %doc):
+12.6. Dokumentacja (pliki %doc)
+
Każdy pakiet powinien w miarę możliwości zawierać odpowiednie pliki
dokumentacji. Pliki dokumentacji należy oznaczać za pomocą %doc, co
umożliwia później użytkownikowi zainstalowanie pakietu bez dokumentacji
@@ -498,6 +546,8 @@
- umieszczać plików standardowych licencji, zawartych w pakiecie
common-licenses
+12.7. Konta systemowe tworzone przez pakiety
+
Konta systemowe i grupy tworzone przez pakiety:
Czasami zdarza się, pakiet potrzebuje utworzyć użytkownika i/lub grupę.
Przykładowo jeżeli jest to demon,który ma być uruchamiany z ograniczonymi
@@ -511,6 +561,7 @@
- dodajemy odpowiednie zależności. Szczegóły można przeczytać w pliku
cvs://PLD-doc/BuildRequires.txt.
+13. Uaktualnianie pakietów
Uaktualniając pakiet należy przejrzeć nakładane patche. Łaty są nakładane
nie bez powodu i niedopuszczalne jest ich usuwanie tylko dlatego, że "bez
@@ -548,8 +599,12 @@
z serwerów wskazywanych przez adres ftp.sourceforge.net obsługują protokół
FTP.
+14. Wprowadzanie podpakietów
+
+TODO: przetłumaczyć z en
+
+15. Branche (gałęzie) w CVS
-Branche (gałęzie) w CVS.
Często pakiet rozwija się w wielu gałęziach (np. bo jest to nowa wersja,
bo inny developer też rozwija i nie chcemy mu przeszkadzać, bo pakiet jest
przeznaczony dla innej wersji PLD (Ra/Ac/Th/...)
@@ -576,17 +631,22 @@
Warto przeczytać początek zawartości skryptu builder - zawiera ona opis
dostępnych opcji.
-Tagowanie.
+16. Tagowanie
+{{{TODO: to chyba nieaktualne, odkąd RA jest martwe, wszystkie autotagi
+zaweirają prefix auto-
NIE WOLNO TAGOWAĆ NUMEREM WERSJI (ani tworzyć gałęzi), czyli tagować nazwą
składającą się z nazwy pakietu (np. : bind-9_2_2-1). To kompetencja ludzi
-puszczających pakiet na buildery. Nie wolno też stosować tagów o nazwach
-rozpoczynających sie auto- (np. auto-ac-glibc-2_3_2-3). Są one używane do
-automatycznego tagowania przez buildery. Niestosowanie się grozi odebraniem
-R/W. Natomiast tagowanie w innym schemacie jest dozwolone ale należy
-ograniczyć się do uzasadnionych przypadków.
+puszczających pakiet na buildery.
+}}}
+
+Nie wolno też stosować tagów o nazwach rozpoczynających sie auto- (np.
+auto-ac-glibc-2_3_2-3). Są one używane do automatycznego tagowania przez
+buildery. Niestosowanie się grozi odebraniem R/W. Natomiast tagowanie w innym
+schemacie jest dozwolone ale należy ograniczyć się do uzasadnionych
+przypadków.
-Przesuwanie tagów, wprowadzenie zmian.
+16.1 Przesuwanie tagów, wprowadzenie zmian
Należy rozróżniać kiedy tag wynika z gałęzi, a kiedy jest to tag symboliczny
(często tak w przypadku patchy).
@@ -601,53 +661,14 @@
#zmiany w <nazwa>.patch
cvs tag -F <tag> <nazwa>.patch
-Usuwanie zbędnych tagów/branchy:
+16.2. Usuwanie zbędnych tagów/branchy
+
Tag lub branch uznajemy za zbędny w przypadku zmergowania jego zawartości z głównym drzewkiem.
Ma to najczęściej miejsce w przypadku brancha DEVEL. Po udanym mergu z DEVEL na HEAD należy więc
usunąć branch DEVEL by nie ogłupiać innych:
cvs tag -d DEVEL <nazwa>.spec
-Przejscie na UNSERMAKE w aplikacjach KDE.
-Wzorcowym specem dla aplikacji KDE jest kdepackage-template.spec. On juz
-jest UNSERMAKE-enabled. Polega to na:
-1. dodaniu BuildRequires: unsermake >= 040511 (koniecznie co najmniej ta wersja)
-2. dodaniu na poczatku %build:
-export UNSERMAKE=/usr/share/unsermake/unsermake (co wlacza unsermake)
-%{__make} -f Makefile.cvs (co powoduje regeneracje buildsystemu pod unsermake)
-
-Troubleshooting:
-1. Jeśli pojawia sie blad, ze TOPSUBDIRS = $(SUBDIRS) to należy przerobić Makefile.am z
-katalogu głównego pakietu tak żeby zamiast $(SUBDIRS) były wpisane normalne
-katalogi (w większości przypadków to będą src doc po).
-
-Można to robić paczem lub ew.
-******************************
-%{__sed} -i -e 's,\$(TOPSUBDIRS),doc po src,' Makefile.am
-******************************
-zamiast doc po src oczywiście te katalogi które powinny być.
-
-Ich listę najłatwiej wziąć z
-******************************
-find -mindepth 2 -maxdepth 2 -name Makefile.am
-******************************
-w katalogu głównym pakietu.
-
-2. Wiele problemow mozna rozwiazac dodajac:
-Source1: http://ep09.pld-linux.org/~djurban/kde/kde-common-admin.tar.bz2
-i -a1 do %setup
-Nie ma sensu jednak tego dodawac w przypadku, gdy chodzi tylko o TOPSUBDIRS=SUBDIRS.
-
-3. ERROR:doc/Makefile.am: KDE_LANG is not a value but a(n empty) list
-omijamy robiąc s/KDE_LANG/SUBDIRS/ i wykomentowując stare SUBDIRS.
-
-4. ERROR:po/Makefile.am tries to overwrite the PHONY status of all
-omijamy robiac echo "POFILES=AUTO" > po/Makefile.am
-
-5. ERROR:src/Makefile.am: USE_AUTOMOC is unsupported
-omijamy zamieniajac USE_AUTOMOC na AUTO.
-
-
-Aplikacje webowe:
+17. Aplikacje webowe
W pliku CVS://template-specs/webapp.spec znajduje się szablon dla aplikacji
www. Należy korzystać z tego szablonu paczkując aplikacje webowe. Więcej
@@ -656,6 +677,7 @@
TODO: jak paczkować aplikacje webowe i konfigurować je przy użyciu webapps.
+{{{TODO: to jeszcze aktualne?
Jeśli wcześniejsze wersje danej aplikacji grzebały w apache.conf lub
httpd.conf, należy dodać odpowiedni trigger dla konwersji do nowego
schematu. Przykładowy trigger można znaleźć w template-apache-package.spec .
@@ -665,9 +687,9 @@
Jeśli aplikacja uprzednio trzymała konfigurację w katalogu apache'a,
także należy dodać trigger dla jego przeniesienia (dla przykładu, patrz
template-apache-package.spec).
+}}}
-
-Nazewnictwo plików innych niż .spec
+18. Nazewnictwo plików innych niż .spec
Kilka bezpodstawnych konwencji:
- NAZWA-foo.patch - łatki
@@ -684,24 +706,23 @@
zmiana plików crontab, skryptów inicjalizacyjnych czy też sysconfig,
łatwo będzie odnaleźć te pliki w CVS-ie.
+19. Perl
-PERL
-
-perllocal.pod
+19.1. perllocal.pod
Zwykle po zainstalowaniu perlowego pakietu z CPAN powstaje niespakietowany
plik /usr/lib/perl5/5.8.6/i686-pld-linux-thread-multi/perllocal.pod. Żeby
uniknąć instalacji tego pliku, należy w specu użyć make pure_install,
zgodnie z przykładem w template-perl.spec.
-Tworzenie nowych pakietów perla (CPAN)
+19.2. Tworzenie nowych pakietów perla (CPAN)
Używać należy wrappera ./new-span.sh. Potrzebne są do tego pakiety
cpan2rpm oraz pldcpan. W zasadzie pldcpan powinien być poprawiony tak,
żeby sam ściągał pakiety z CPAN. Aktualnie do ściągania używany jest
cpan2rpm.
-Czterocyfrowe numery wersji (1.2301)
+19.3. Czterocyfrowe numery wersji (1.2301)
Dla pakietów rpm należy używać schematu numerów wersji 1.23_01. Przykład można
zobaczyć w:
@@ -713,9 +734,12 @@
TODO usuwać:
/usr/lib/perl5/vendor_perl/5.8.0/i686-pld-linux-thread-multi/auto/gpg-ezmlm/.packlist
-
-PHP PEAR.
+20. PHP PEAR
Pakiety php-pear należy tworzyć używając polecenia `pear makerpm NAZWAPEAR`.
Wynik nie jest doskonały, więc trzeba go następnie nieco uporządkować.
Binarkę pear można znaleźć w pakiecie php-pear-PEAR.
+
+21. Java
+
+TODO
================================================================
---- CVS-web:
http://cvs.pld-linux.org/cgi-bin/cvsweb.cgi/PLD-doc/devel-hints-pl.txt?r1=1.66&r2=1.67&f=u
More information about the pld-cvs-commit
mailing list