dpkg-source(1)

NAZWA
dpkg-source - narzędzia do zarządzania źródłowymi pakietami Debiana (.dsc)

SKŁADNIA
dpkg-source [opcje] polecenie

OPIS
dpkg-source tworzy i rozpakowuje źródłowe archiwa (pakiety) Debiana. Żadne z tych poleceń nie pozwala na łączenie wielu opcji w jedną, nie pozwalają również na podawanie wartości opcji jako oddzielnego parametru.

POLECENIA

-x nazwa-pliku.dsc [katalog-wyjściowy]
    Rozpakowanie pakietu źródłowego. Wymagane jest podanie jednego argumentu nie będącego opcją, nazwy pliku kontrolny pakietu źródłowego (.dsc). Ponadto może być podany drugi opcjonalny argument niebędący opcją, określający katalog, do którego pakiet źródłowy ma zostać rozpakowany (katalog ten nie może istnieć). Jeśli nie podano katalogu wyjściowego, pakiet źródłowy jest rozpakowywany do katalogu o nazwie źródło-wersja w ramach bieżącego katalogu roboczego. dpkg-source odczyta nazwy innych plików tworzących pakiet źródłowy z pliku kontrolnego; zakładane jest, że są one w tym samym katalogu co .dsc. Pliki w rozpakowanym pakiecie będą mieć uprawnienia i właściciela zgodnie z typowymi, oczekiwanymi wartościami jak przy zwykłym tworzeniu plików i katalogów - katalogi i pliki wykonywalne będą mieć prawa 0777, zaś zwykłe pliki będą mieć prawa 0666 (w obu przypadkach modyfikowane przez umask rozpakowującego). Ponadto jeśli katalog nadrzędny ma ustawiony bit setgid, rozpakowane katalogi także będą go mieć, zaś wszystkie pliki i katalogi przejmą ustawienia grupy katalogu nadrzędnego. Jeśli pakiet źródłowy używa niestandardowego formatu (aktualnie oznacza to wszystkie formaty poza "1.0"), jego nazwa będzie umieszczona w pliku debian/source/format. Dzięki temu przy następnych budowach pakietu źródłowego będzie domyślnie używany ten sam format.

-b, katalog [parametry-zależne-od-formatu]
    Budowanie pakietu źródłowego. Pierwszy argument nie będący opcją przyjmowany jest jako nazwa katalogu zdebianizowanego drzewa ze źródłami (czyli zawierającego podkatalog "debian" i być może zmiany w stosunku do oryginalnych plików). Zależnie od formatu pakietu źródłowego używanego przy budowaniu pakietu, mogą być również akceptowane dodatkowe parametry. dpkg-source będzie budować pakiet źródłowy z użyciem pierwszego działającego formatu z następującej listy, w kolejności: format określony w polu Format w pliku debian/control, format(y) określone za pomocą opcji --format, format określony w pliku debian/source/format, "1.0", "3.0 (native)". Poniżej znajduje się wyczerpujący opis różnych formatów pakietów źródłowych.

-h, --help
    Wyświetla informację o użytkowaniu i kończy działanie.

--version
    Wyświetla informację o wersji i pomyślnie kończy działanie.

OGÓLNE OPCJE BUDOWANIA

-cplik_kontrolny
    Określa główny plik kontrolny źródeł, z którego będą czytane informacje. Domyślnie jest to debian/control. Jeśli podano względną ścieżkę, to jest ona interpretowana od najwyższego poziomu katalogu drzewa ze źródłami.

-ldziennik_zmian
    Określa dziennik zmian, z którego będą czytane informacje. Domyślnie jest to debian/changelog. Jeśli podano względną ścieżkę, to jest ona interpretowana od najwyższego poziomu katalogu drzewa ze źródłami.

-Fformat_dziennika_zmian
    Określa format dziennika zmian. Domyślnie format jest czytany ze specjalnej linii znajdującej się przy końcu pliku lub - jeśli taka linia nie istnieje - używany jest standardowy format Debiana.

--format=wartość
    Do budowy pakietu źródłowego próbowany jest najpierw podany format. Jeśli opcja ta jest użyta wielokrotnie, są próbowane w podanej kolejności. Nie nadpisuje to żadnego jawnego pola Format z debian/control ale nadpisuje każdy format podany w pliku debian/source/format.

-Vnazwa=wartość
    Przestarzałe. Ustawia zmienną podstawienia wyjścia. Szczegółowy opis podstawiania wyjścia znajduje się w deb-substvars(5).

-Tplik_zmiennych_podst
    Przestarzałe. Czyta zmienne podstawiania z pliku_zmiennych_podst; domyślnie nie czyta żadnego pliku.

-Dpole=wartość
    Nadpisuje lub dodaje wyjściowe pole pliku kontrolnego.

-Upole
    Usuwa wyjściowe pole pliku kontrolnego.

-Zkompresja
    Określa rodzaj kompresji używanej podczas tworzenia plików (archiwów tar oraz plików różnic). Uwaga: opcja ta nie spowoduje, że istniejące archiwa tar będą ponownie kompresowane, lecz ma zastosowanie tylko do plików nowo tworzonych. Obsługiwane wartości: gzip, bzip2 oraz lzma. gzip jest wartością domyślną.

-zpoziom
    Używany poziom kompresowania. Podobnie jak w wypadki -Z, dotyczy tylko nowo tworzonych plików. Obsługiwane wartości: 1 do 9, best oraz fast. 9 jest wartością domyślną.

-i[wyraż_regularne]
    Należy podać wyrażenie regularne Perla pasujące do listy plików, które mają nie być uwzględniane podczas tworzenia pliku różnic (lista ta jest tworzona poleceniem find). (Jeśli zaś pakiet źródłowy jest budowany w formacie 3.0 z użyciem systemu kontroli wersji, jest ono używane to ignorowania niezatwierdzonych plików.) -i podane bez żadnych argumentów włącza tę opcję, domyślnie odfiltrowując pliki kontrolne i katalogi najpopularniejszych systemów kontroli wersji, kopie zapasowe, pliki wymiany oraz katalogi wyjściowe libtoola. Tylko jedno wyrażenie regularne może być aktywne, jeśli opcję -i podano kilkakrotnie, to tylko ostatnia z nich będzie wzięta pod uwagę. Jest to bardzo przydatne do wykluczania nieistotnych plików, które zostałyby włączone do pliku różnic (diff). Przykładem może być sytuacja, gdzie kod źródłowy jest zarządzany przez system kontroli wersji i kod pobrany z repozytorium ma być użyty do zbudowania pakietu źródłowego, bez włączania w to dodatkowych plików i katalogów związanych z obsługą repozytorium (np. CVS/, .cvsignore, .svn/). Domyślne wyrażenie regularne jest już całkiem obszerne, ale jeśli istnieje potrzeba zastąpienia go, należy zauważyć że domyślnie może ono pasować do dowolnej części ścieżki - dlatego w celu dopasowania do początku nazwy pliku lub jedynie pełnych nazw plików, konieczne jest samodzielne użycie odpowiednich wyrażeń (np. "(^|/)", czy "($|/)").

-I [wzorzec-pliku]
    Po podaniu tej opcji, wzorzec będzie przekazany jako parametr dla --exclude polecenia tar(1), używanego do stworzenia archiwum .orig.tar lub .tar. Na przykład, -ICVS powoduje, że tar będzie pomijał katalogi CVS przy tworzeniu pliku .tar.gz. Ta opcja może być podana wielokrotnie w celu określenia wielu wzorców wykluczeń. Samo -I podane bez żadnych argumentów ustawia opcje --exclude, domyślnie odfiltrowując pliki kontrolne i katalogi najpopularniejszych systemów kontroli wersji, kopie zapasowe, pliki wymiany oraz katalogi wyjściowe libtoola.

Uwaga: Mimo, że mają podobne przeznaczenie, opcje -i oraz -I mają całkiem odmienną składnię i semantykę. -i może być podana tylko raz i przyjmuje wyrażenie regularne Perla, które jest dopasowywane do pełnej ścieżki względnej każdego pliku. -I może być podana wielokrotnie i przyjmuje wzorzec nazw plików wraz ze znakami specjalnymi powłoki (wildcards). Wzorzec jest dopasowywany do pełnej ścieżki względnej, ale również indywidualnie do każdej części ścieżki. Pełna semantyka opcji --exclude programu tar jest nieco skomplikowana, proszę sprawdzić http://www.gnu.org/software/tar/manual/tar.html#wildcards w celu uzyskania dokładnych informacji. Domyślne wyrażenia regularne i wzorce dla obu opcji można znaleźć w wyjściu polecenia --help.

OGÓLNE OPCJE ROZPAKOWYWANIA

--no-copy
    Nie kopiuje oryginalnych archiwów obok rozpakowanego pakietu źródłowego.

--no-check
    Bez weryfikacji podpisów i sprawdzania sum kontrolnych przed rozpakowaniem.

FORMATY PAKIETÓW ŹRÓDŁOWYCH

  Format: 1.0
Pakiet źródłowy w tym formacie składa się z pliku .orig.tar.gz powiązanego z plikiem różnic .diff.gz, lub z pojedynczego pliku .tar.gz (w takim przypadku mówi się, że pakiet jest natywny). Rozpakowywanie Rozpakowanie pakietu natywnego to proste rozpakowanie pojedynczego pliku archiwum w katalogu docelowym. Rozpakowanie pakietu w stylu Debiana (non-native) odbywa się poprzez najpierw rozpakowanie pliku .orig.tar.gz a następnie nałożenia łatek zawartych w pliku .diff.gz. Czasy modyfikacji wszystkich łatanych plików są ustawiane na wartość odpowiadającą czasowi rozpakowania pakietu źródłowego (zapobiega to przesunięciom czasów, które prowadzą do problemów przy łataniu plików generowanych automatycznie). Plik różnic (diff) może tworzyć nowe pliki (cały katalog "debian" jest tak tworzony), ale nie może usuwać plików (pozostawiane są puste pliki o zerowej długości). Budowanie Budowanie pakietu natywnego to proste stworzenie pojedynczego pliku archiwum z katalogu źródeł. Budowanie pakietu w stylu Debiana (non-native) obejmuje rozpakowanie oryginalnego archiwum do oddzielnego katalogu z przyrostkiem ".orig" i regenerację pliku .diff.gz poprzez porównanie katalogu pakietu źródłowego z katalogiem ".orig".

Opcje budowania (z -b):

Buduje pakiet źródłowy. Należy podać jeden lub dwa argumenty, nie będące opcjami. Pierwszym z nich jest nazwa katalogu zawierającego rozpakowane źródła. Jeżeli podano drugi argument, to powinien on być nazwą oryginalnego katalogu ze źródłami lub archiwum tar albo pustym łańcuchem znaków, jeśli pakiet jest specyficzny dla Debiana i nie ma pliku różnic. Jeżeli nie podano drugiego argumentu, to dpkg-source - w zależności od argumentów -sX - będzie szukał albo archiwum tar z oryginalnymi źródłami pakiet_wersja_upstream.orig.tar.rozszerzenie (gdzie rozszerzenie jest jednym z gz,bz2 lub lzma), albo katalogu z oryginalnymi źródłami katalog.orig. -sa, -sp, -sk, -su oraz -sr nie nadpiszą istniejących archiwów tar lub katalogów. Jeśli jest to wymagane, należy użyć -sA, -sP, -sK, -sU i -sR.

-sk Określa, że należy spodziewać się oryginalnych źródeł w postaci archiwum tar, domyślnie pakiet_wersja-autora-pakietu.orig.tar.rozszerzenie. Pozostawia oryginalne źródła w tym samym miejscu jako plik tar lub kopiuje je do bieżącego katalogu jeśli jeszcze ich tam nie ma. Archiwum będzie rozpakowane do katalogu.orig w celu utworzenia pliku różnic (diff).

-sp Jak -sk, ale ponownie usunie katalog po zakończeniu.

-su Określa, że należy spodziewać się oryginalnych źródeł w postaci katalogu, domyślnie pakiet-wersja-autora-pakietu.orig, na podstawie którego dpkg-source utworzy nowe archiwum oryginalnych źródeł.

-sr Jak -su, jednakże usunie katalog po jego użyciu.

-ss Określa, że oryginalne źródła są dostępne zarówno jako katalog oraz jako archiwum tar. dpkg-source będzie utworzy plik różnic na podstawie katalogu, ale użyje pliku tar do utworzenia pliku .dsc. Należy używać tej opcji z rozwagą - jeśli katalog oraz plik tar sobie nie odpowiadają, zostanie wygenerowane niepoprawne archiwum źródłowe.

-sn Określa aby nie szukać żadnych oryginalnych źródeł, ani nie generować pliku różnic. Jeśli jest podany drugi argument, musi on być pustym ciągiem znaków. Jest to używane dla pakietów specyficznych dla Debiana, które nie mają oddzielnych źródeł i w związku z tym nie mają debianizujących plików różnic (diff).

-sa lub -sA
    Określa, że należy szukać oryginalnych źródeł w postaci archiwum tar lub katalogu. Jeśli podano drugi argument może wskazywać on plik lub katalog, albo być pustym ciągiem znaków (co jest równoważne użyciu -sn). Jeśli znaleziony zostanie plik tar, będzie on rozpakowany w celu utworzenia pliku różnic, po czym zostanie on usunięty (co jest równoważne -sp). Jeśli zostanie znaleziony katalog, będzie on spakowany w celu utworzenia archiwum źródłowego, po czym zostanie on usunięty (co jest równoważne -sr).

Opcje rozpakowywania (z -x):

We wszystkich przypadkach, istniejące oryginalne drzewo ze źródłami będzie usunięte.

-sp Jeśli zostanie użyta przy wypakowywaniu, wtedy oryginalne źródła (jeśli są) pozostaną w formie archiwum tar. Jeśli archiwum nie ma jeszcze w bieżącym katalogu, lub gdy istnieje ale jest to inny plik, zostanie tam skopiowane. (Jest to zachowanie domyślne).

-su Rozpakowuje oryginalne drzewo źródeł programu.

-sn Zapewnia, że oryginalne źródła nie będą kopiowane do bieżącego katalogu ani rozpakowywane. We wszystkich przypadkach, istniejący katalog ze źródłami będzie usunięty z bieżącego katalogu.

Wszystkie spośród opcji -s-X się wzajemnie wykluczają. Jeśli zostanie podana więcej niż jedna, to zostanie użyta ostatnia z nich.

  Format: 2.0
Znany również jako wig&pen. Ten format nie jest zalecany do szerokiego stosowania, zastępuje go format "3.0 (quilt)". Wig&pen był pierwszą specyfikacją nowej generacji formatu pakietów źródłowych. Zachowanie dla tego formatu jest takie samo jak dla "3.0 (quilt)" z tą różnicą, że nie używa jawnej listy łatek. Wszystkie pliki w katalogu debian/patches/ pasujące do wyrażenia regularnego Perla [\w-]+ muszą być prawidłowymi łatkami: są one nakładane podczas rozpakowywania. Podczas budowania nowego pakietu źródłowego, wszystkie zmiany w stosunku do kodu źródłowego pochodzącego od autorów programu są zapisywane w łatce o nazwie zz_debian-diff-auto.

  Format: 3.0 (native)
Ten format jest rozszerzeniem natywnego formatu pakietów zdefiniowanego w formacie w wersji 1.0. Obsługuje wszystkie metody kompresji i domyślnie ignoruje pliki i katalogi specyficzne dla systemów kontroli wersji, jak również wiele typów plików tymczasowych (proszę sprawdzić opis domyślnej wartości opcji -I w informacjach uzyskiwanych poleceniem --help).

  Format: 3.0 (quilt)
Pakiet źródłowy w tym formacie zawiera co najmniej oryginalne archiwum tar (.orig.tar.rozszerzenie, gdzie rozszerzeniem może być gz, bz2 i lzma) oraz archiwum debian (.debian.tar.rozszerzenie). Może również zawierać dodatkowe oryginalne archiwa (.orig-komponent.tar.rozszerzenie).

Rozpakowywanie

Najpierw rozpakowywane jest główne oryginalne archiwum, następnie rozpakowywane są dodatkowe oryginalne archiwa do podkatalogów nazwanych od części komponent z ich nazwy pliku (istniejące katalogi o takich nazwach są zamieniane). Na końcu rozpakowywane jest archiwum debian, po uprzednim usunięciu katalogu debian (jeśli taki istniał). Należy zauważyć, że archiwum debian musi zawierać podkatalog debian, ale może również zawierać pliki binarne poza tym katalogiem (proszę sprawdzić opcję --include-binaries).

Następnie nakładane są wszystkie łatki wymienione w debian/patches/debian.series lub debian/patches/series. Jeśli jest użyty pierwszy z tych plików a drugi z nich nie istnieje (lub jest łączem symbolicznym), wtedy ten drugi plik jest zastępowany łączem symbolicznym do pierwszego pliku. Ma to uprościć używanie quilt do zarządzania zbiorem łatek. Należy zauważyć, że o ile dpkg-source poprawnie przetwarza pliki series z podanymi jawnie opcjami programu patch (zapisanymi w każdej z linii po nazwie pliku z łatką i jednej lub więcej spacji), to jednak ignoruje te opcje i zawsze oczekuje łatek, które można nałożyć używając opcji -p1 programu patch. Po napotkaniu takich opcji wysyłane jest ostrzeżenie, zaś proces budowania prawdopodobnie się nie powiedzie.

Podobnie do domyślnego zachowania quilt, łatki mogą także usuwać pliki.

Jeśli podczas rozpakowywania zostały nałożone jakieś łatki, tworzony jest plik debian/patches/.dpkg-source-applied.

Budowanie

Wszystkie oryginalne archiwa znalezione w bieżącym katalogu są rozpakowywane do katalogu tymczasowego w taki sam sposób jak dla unpack, następnie katalog debian jest kopiowany do katalogu tymczasowego i nakładane są wszystkie łatki, z wyłączeniem jedynie debian-changes-wersja. Katalog tymczasowy jest porównywany z katalogiem pakietu źródłowego a plik różnic (jeśli jest niepusty) jest zapisywany w debian/patches/debian-changes-wersja. Żadne zmiany w jakimkolwiek pliku binarnym nie mogą być odwzorowane w pliku zmian, co doprowadzi do niepowodzenia - chyba, że opiekun pakietu rozmyślnie zdecydował o włączeniu tak zmodyfikowanego pliku binarnego do archiwum debian (wskazując go w debian/source/include-binaries). Proces budowania nie powiedzie się także jeśli zostaną znalezione pliki binarne w podkatalogu debian, chyba że zostały one uprzednio wymienione w debian/source/include-binaries. Zaktualizowany katalog debian oraz lista zmodyfikowanych plików binarnych są następnie używane do powtórnego wygenerowania archiwum debian. Automatycznie wygenerowany plik różnic nie zawiera zmian w plikach specyficznych dla systemów kontroli wersji, jak również w wielu typach plików tymczasowych (proszę sprawdzić opis domyślnej wartości opcji -i w informacjach uzyskiwanych poleceniem --help). W szczególności, katalog .pc używany przez quilt jest ignorowany podczas automatycznego generowania łatki. Uwaga: dpkg-source zakłada, że drzewo ze źródłami będzie mieć nałożone wszystkie łatki podczas generowania pakietu źródłowego. Nie jest tak, jeśli drzewo źródeł zostało uzyskane przez rozpakowanie pakietu źródłowego używającego na przykład Format: 1.0. Aby temu zapobiec, dpkg-source także nakłada łatki przed budowaniem chyba, że znajdzie debian/patches/.dpkg-source-applied. Obecność podkatalogu .pc jest również interpretowana jako oznaka, że jakieś łatki zostały już nałożone. W takim przypadku wywoływane jest quilt unapplied w celu weryfikacji, czy wszystkie łatki zostały nałożone. Może być użyta opcja --no-preparation aby wyłączyć to zachowanie.

Opcje budowania

--include-removal
    Usunięte pliki nie będą ignorowane, ale będą włączone do automatycznie generowanej łatki.

--include-timestamp
    Włączenie czasu modyfikacji w automatycznie generowanej łatce.

--include-binaries
    Dodanie wszystkich zmodyfikowanych plików binarnych do archiwum debian. Są one również dodawane do debian/source/include-binaries: dzięki temu będą domyślnie dodawane przy następnych budowach pakietu, zaś ta opcja nie będzie już więcej potrzebna.

--no-preparation
    Nie próbuje przygotowywać drzewa budowania poprzez nakładanie łatek, które wyraźnie nie są nałożone.

Opcje rozpakowywania

--skip-patches
    Nie nakłada łatek po skończeniu rozpakowywania.

--without-quilt
    Nie używa quilt do nakładania łatek, ale własnego kodu dpkg-source. Nie będzie można używać quilt bezpośrednio na rozpakowanym katalogu, ale nie będzie on również zawierać plików tymczasowych quilt.

  Format: 3.0 (custom)
Ten format jest szczególny. Nie jest prawdziwym formatem pakietu źródłowego, ale może być użyty do stworzenia pakietu źródłowego zawierającego dowolne pliki.

Opcje budowania

Wszystkie argumenty nie będące opcjami są uważane za pliki, które mają być zintegrowane z generowanym pakietem źródłowym. Pliki te muszą istnieć i najlepiej powinny być w bieżącym katalogu. Musi być podany przynajmniej jeden plik.

--target-format=wartość
    Wymagane. Określa prawdziwy format generowanego pakietu źródłowego. Generowany plik .dsc będzie zawierać tą wartość w swoim polu Format zamiast "3.0 (custom)".

  Format: 3.0 (git) oraz 3.0 (bzr)
Te formaty są eksperymentalne. Generują pojedyncze archiwa tar zawierające odpowiednie repozytoria systemu kontroli wersji.

Rozpakowywanie

Archiwum tar jest rozpakowywane i system kontroli wersji jest używany aby pobrać aktualną gałąź kodu.

Budowanie

Nie zagłębiając się dalej, wykonywane są pewne testy aby upewnić się, czy nie ma żadnych niezatwierdzonych zmian, które nie są ignorowane.

Następnie część katalogu źródeł specyficzna dla systemu kontroli wersji jest kopiowana do katalogu tymczasowego. Przed tym katalog tymczasowy jest pakowany do archiwum tar i wykonywane są różne czynności porządkowe, aby zaoszczędzić miejsce.

BŁĘDY
Punkt, w którym następuje nadpisywanie pól w porównaniu do pewnych standardowych ustawień pól wyjściowych jest dość zagmatwany.

ZOBACZ TAKŻE
dpkg-deb(1), dpkg(1), dselect(1).

AUTORZY
Copyright (C) 1995-1996 Ian Jackson
Copyright (C) 2000 Wichert Akkerman
Copyright (C) 2008 Raphaël Hertzog

Niniejszy program jest oprogramowaniem wolnym, sprawdź Powszechną Licencję Publiczną GNU w wersji drugiej lub późniejszej, by dowiedzieć się o warunkach dystrybucji. Brak JAKIEJKOLWIEK gwarancji.

TŁUMACZE
Piotr Roszatycki <dexter@debian.org>, 1999
Bartosz Feński <fenio@debian.org>, 2004-2005
Robert Luberda <robert@debian.org>, 2006-2008
Wiktor Wandachowicz <siryes@gmail.com>, 2008