Instalacja Pakietów w SageMath: Przewodnik Krok po Kroku

SageMath, potężne oprogramowanie matematyczne, oferuje ogromną elastyczność dzięki swojej architekturze opartej na pakietach. Jedną z kluczowych zasad projektu Sage jest unikanie ponownego odkrywania koła – jeśli dany algorytm jest już zaimplementowany w dobrze przetestowanej bibliotece, warto rozważyć włączenie tej biblioteki do Sage. W tym artykule szczegółowo omówimy, jak instalować pakiety w SageMath, abyś mógł w pełni wykorzystać jego potencjał.

Gdzie Znajdują Się Pakiety SageMath?

Aktualna lista dostępnych pakietów znajduje się w podkatalogach katalogu SAGE_ROOT/build/pkgs/. Każdy podkatalog reprezentuje oddzielny pakiet, zawierający wszystkie niezbędne pliki do jego instalacji i konfiguracji.

Skrypt Instalacyjny: sage-spkg

Proces instalacji pakietów w SageMath jest zarządzany przez skrypt bash o nazwie sage-spkg, znajdujący się w katalogu SAGE_ROOT/build/bin/. Ten skrypt jest kluczowym narzędziem, które umożliwia dodawanie nowych funkcjonalności do SageMath poprzez instalację zewnętrznych bibliotek i rozszerzeń.

Aby zainstalować pakiet, zazwyczaj wywołuje się skrypt sage-spkg z linii poleceń, podając nazwę pakietu jako argument. Podstawowa składnia polecenia wygląda następująco:

./sage -pkg install <nazwa_pakietu> 

Na przykład, aby zainstalować pakiet o nazwie "foo", należy użyć polecenia:

./sage -pkg install foo 

Opcje Skryptu sage-spkg

Skrypt sage-spkg oferuje kilka opcji, które pozwalają dostosować proces instalacji:

• -c: Po pomyślnej instalacji pakietu, ta opcja uruchamia zestaw testów dla zainstalowanego pakietu. Jest to przydatne do upewnienia się, że pakiet został zainstalowany poprawnie i działa zgodnie z oczekiwaniami. Opcja -c nadpisuje ustawienia zmiennych środowiskowych SAGE_CHECK i SAGE_CHECK_PACKAGES.
• -f: Ta opcja wymusza instalację pakietu, nawet jeśli ta sama wersja pakietu jest już zainstalowana w systemie. Może to być przydatne w sytuacjach, gdy chcesz przeinstalować pakiet lub upewnić się, że używana jest określona wersja.

Struktura Katalogów Pakietów

Każdy pakiet w SAGE_ROOT/build/pkgs/ ma określoną strukturę katalogów, która jest kluczowa dla prawidłowej instalacji. Standardowa struktura katalogu pakietu "foo" wygląda następująco:

SAGE_ROOT/build/pkgs/foo ├── checksums.ini ├── dependencies ├── package-version.txt ├── spkg-install.in ├── SPKG.rst └── type 

Poniżej omówimy kluczowe pliki w strukturze katalogu pakietu:

• checksums.ini: Ten plik zawiera informacje o sumach kontrolnych i nazwach plików archiwum źródłowego pakietu. Jest używany do weryfikacji integralności pobranego archiwum.
• dependencies: Plik dependencies określa zależności pakietu od innych pakietów SageMath. To pozwala systemowi SageMath na zarządzanie kolejnością instalacji i zależnościami między pakietami.
• package-version.txt: Zawiera numer wersji pakietu. SageMath używa tego pliku do śledzenia zainstalowanych wersji pakietów i ponownego uruchamiania instalacji, jeśli wersja pakietu ulegnie zmianie.
• spkg-install.in: Jest to szablon skryptu instalacyjnego w bashu. Skrypt spkg-install, generowany na podstawie tego szablonu, jest odpowiedzialny za właściwą instalację pakietu w systemie.
• SPKG.rst: Plik w formacie reStructuredText zawierający opis pakietu, informacje o licencji, kontakt do twórców i ewentualne specjalne instrukcje dotyczące aktualizacji lub budowy.
• type: Ten plik tekstowy określa typ pakietu, który może być standard, optional lub experimental. Typ pakietu wpływa na to, czy pakiet jest domyślnie budowany i jakie są wymagania jakościowe.

Oprócz wymienionych plików, katalog pakietu może zawierać dodatkowe pliki, takie jak:

SAGE_ROOT/build/pkgs/foo ├── distros │ ├── platform1.txt │ └── platform2.txt ├── has_nonfree_dependencies ├── huge ├── patches │ ├── bar.patch │ └── baz.patch ├── spkg-check.in ├── spkg-configure.m4 ├── spkg-src └── trees.txt 

Te dodatkowe pliki służą do obsługi specyficznych przypadków, takich jak dystrybucje systemowe, zależności nie-wolne, duże pakiety, łatki, testy pakietów, konfiguracja systemu i określanie drzew instalacyjnych.

Typy Pakietów

Pakiety w SageMath są klasyfikowane na podstawie ich typu, co wpływa na sposób ich budowy i włączania do systemu:

• Pakiety Standardowe: Są to pakiety, które są budowane domyślnie i stanowią podstawową funkcjonalność SageMath. Pakiety standardowe muszą spełniać surowe wymagania jakościowe i działać na wszystkich obsługiwanych platformach. Nowy pakiet standardowy musi najpierw przejść fazę pakietu opcjonalnego.
• Pakiety Opcjonalne: Pakiety opcjonalne nie są budowane domyślnie, ale mogą być włączone przez użytkownika. Powinny one również działać na wszystkich obsługiwanych platformach, a testy opcjonalne w bibliotece Sage powinny być pomyślne. Pakiety opcjonalne są mniej intensywnie testowane niż pakiety standardowe.
• Pakiety Eksperymentalne: Pakiety eksperymentalne są przeznaczone do testowania nowych funkcji i bibliotek. Wymagania jakościowe dla pakietów eksperymentalnych są niższe, co pozwala na włączanie pakietów nawet z pewnymi problemami.

Typy Źródeł Pakietów

Pakiety w SageMath różnią się również typem źródła, z którego są instalowane. Rozróżniamy następujące typy:

• Pakiety Skryptowe: Charakteryzują się obecnością skryptu spkg-install lub spkg-install.in. Instalacja pakietu skryptowego polega na uruchomieniu tego skryptu. Wiele pakietów skryptowych ma drzewo źródłowe w repozytorium Sage.
• Pakiety Pip: Są identyfikowane przez obecność pliku requirements.txt. Instalacja pakietu pip odbywa się za pomocą narzędzia pip, które zarządza zależnościami Pythona. Standardowo, pakiety pip nie są zalecane jako standardowe pakiety SageMath.
• Pakiety Wheel: Pakiety wheel są rozpoznawane po pliku checksums.ini i braku pliku requirements.txt. Pochodzą z plików wheel (.whl) hostowanych na serwerach lustrzanych Sage. Instalacja pakietu wheel nie wymaga skryptów budowania ani instalacji, z wyjątkiem pakietu pip, który instaluje się za pomocą niestandardowego skryptu.
• Pakiety Normalne: Pakiety normalne, podobnie jak pakiety wheel, posiadają plik checksums.ini, ale nie mają pliku requirements.txt. Pochodzą z archiwów tarball (.tar.gz) hostowanych na serwerach lustrzanych Sage. Instalacja pakietów normalnych odbywa się za pomocą skryptów budowania i instalacji (spkg-build i spkg-install).
• Pakiety Dummy: Pakiety dummy nie posiadają skryptu spkg-install i służą jedynie do rejestrowania nazw równoważnych pakietów systemowych. Próba instalacji pakietu dummy za pomocą SageMath spowoduje wyświetlenie komunikatu o błędzie.

Proces Instalacji Pakietu Normalnego

Proces instalacji pakietu normalnego z archiwum tarball zazwyczaj przebiega następująco:

1. Pobranie Archiwum: SageMath pobiera archiwum tarball pakietu z serwera lustrzanego, korzystając z informacji zawartych w pliku checksums.ini.
2. Weryfikacja Sumy Kontrolnej: Suma kontrolna pobranego archiwum jest weryfikowana w celu zapewnienia integralności pliku.
3. Rozpakowanie Archiwum: Archiwum tarball jest rozpakowywane do katalogu roboczego.
4. Uruchomienie Skryptów: W zależności od konfiguracji pakietu, uruchamiane są skrypty spkg-build i spkg-install. Skrypt spkg-build jest odpowiedzialny za proces budowania pakietu (np. kompilację kodu źródłowego), a skrypt spkg-install za instalację zbudowanych plików w odpowiednich lokalizacjach w systemie SageMath ($SAGE_LOCAL).
5. Rejestracja Wersji: SageMath rejestruje zainstalowaną wersję pakietu w pliku $SAGE_LOCAL/var/lib/sage/installed/. W przypadku zmiany pliku package-version.txt, instalacja pakietu zostanie ponownie uruchomiona.

Skrypty Budowania i Instalacji (spkg-build.in, spkg-install.in)

Pliki spkg-build.in i spkg-install.in są szablonami dla skryptów bash spkg-build i spkg-install, które odpowiednio budują i instalują pakiet. Szablony *.in nie powinny zawierać linii shebang (#!...) i nie powinny mieć ustawionego bitu wykonywalności. Są one dodawane automatycznie podczas generowania skryptów, wraz z dodatkowym boilerplate, podczas instalacji pakietu.

Skrypty spkg-build.in i spkg-install.in w drzewie źródłowym Sage powinny skupiać się tylko na specyficznych krokach budowania i instalacji danego pakietu. Jeśli plik spkg-build.in nie istnieje, to spkg-install.in jest odpowiedzialny za oba kroki, chociaż zaleca się ich rozdzielenie, gdy jest to możliwe.

Możliwe jest również dołączenie podobnych szablonów skryptów o nazwach spkg-preinst.in lub spkg-postinst.in, aby uruchomić dodatkowe kroki przed lub po instalacji pakietu w $SAGE_LOCAL. Zaleca się umieszczanie kroków, które modyfikują już zainstalowane pliki, w oddzielnym skrypcie spkg-postinst.in, zamiast łączenia ich z spkg-install.in.

W najlepszym przypadku, projekt upstream można po prostu zainstalować za pomocą standardowych kroków configure / make / make install. W takim przypadku, szablon skryptu spkg-build.in składałby się po prostu z:

cd src sdh_configure sdh_make 

A szablon skryptu spkg-install.in z:

cd src sdh_make_install 

Katalog najwyższego poziomu w archiwum tarball jest zmieniany na src przed wywołaniem skryptów spkg-build i spkg-install, więc można po prostu użyć cd src zamiast cd foo-1.3.

Funkcje Pomocnicze (sdh_)

W skryptach spkg-build, spkg-install i spkg-check dostępne są funkcje pomocnicze, które ułatwiają tworzenie skryptów instalacyjnych i zapewniają spójność. Funkcje te są zdefiniowane w pliku SAGE_ROOT/build/bin/sage-dist-helpers i ich nazwy zaczynają się od sdh_ (Sage-distribution helper).

Przykładowe funkcje pomocnicze:

• sdh_die MESSAGE: Kończy skrypt budowania z kodem błędu ostatniego polecenia (jeśli był różny od zera) lub z kodem 1 w przeciwnym razie, i wyświetla komunikat o błędzie.
• sdh_check_vars [VARIABLE ...]: Sprawdza, czy jedna lub więcej zmiennych jest zdefiniowanych i niepustych, i kończy program z błędem, jeśli któraś jest niezdefiniowana lub pusta.
• sdh_configure [...]: Uruchamia ./configure z argumentami --prefix="$SAGE_LOCAL", --libdir="$SAGE_LOCAL/lib", --disable-static, --disable-maintainer-mode i --disable-dependency-tracking. Dodatkowe argumenty dla ./configure można podać jako argumenty funkcji.
• sdh_make [...]: Uruchamia $MAKE z domyślnym celem. Dodatkowe argumenty dla $MAKE można podać jako argumenty funkcji.
• sdh_make_install [...]: Uruchamia $MAKE install z DESTDIR poprawnie ustawionym na tymczasowy katalog instalacyjny. Dodatkowe argumenty dla $MAKE można podać jako argumenty funkcji. Jeśli $SAGE_DESTDIR nie jest ustawiony, polecenie jest uruchamiane z $SAGE_SUDO, jeśli jest ustawiony.
• sdh_pip_install [...]: Odpowiednik uruchomienia pip install z podanymi argumentami, a także dodatkowymi domyślnymi argumentami używanymi do instalowania pakietów w Sage za pomocą pip. Ostatnim argumentem musi być ., aby wskazać instalację z bieżącego katalogu.
• sdh_install [-T] SRC [SRC...] DEST: Kopiuje jeden lub więcej plików lub katalogów podanych jako SRC (rekurencyjnie w przypadku katalogów) do katalogu docelowego DEST, zapewniając, że DEST i wszystkie jego katalogi nadrzędne istnieją. DEST powinien być ścieżką w $SAGE_LOCAL.
• sdh_guard: Wrapper dla sdh_check_vars, który sprawdza niektóre popularne zmienne, bez których wiele/większość pakietów nie zbuduje się poprawnie (SAGE_ROOT, SAGE_LOCAL, SAGE_SHARE).

Korzystanie z Pakietów Systemowych

Dla wielu pakietów SageMath można użyć już zainstalowanej wersji systemowej, jeśli jest dostępna i spełnia wymagania. Skrypt ./configure na najwyższym poziomie SageMath określa, kiedy jest to możliwe. Aby to umożliwić, pakiet musi mieć skrypt spkg-configure.m4, który może np. określić, czy zainstalowane oprogramowanie jest wystarczająco aktualne (a czasami nie za stare) do użytku przez SageMath.

Jeśli oprogramowanie dla pakietu SageMath jest dostarczane przez pakiet systemowy, skrypt ./configure może dostarczyć te informacje. W tym celu musi istnieć katalog build/pkgs/PACKAGE/distros zawierający pliki o nazwach takich jak arch.txt, conda.txt, debian.txt, fedora.txt, homebrew.txt, ... odpowiadające różnym systemom pakietów. Każdy pakiet systemowy powinien pojawić się w osobnym wierszu. Na przykład, jeśli ./configure wykryje, że używany jest system pakietów Homebrew, i jeśli bieżący pakiet może być dostarczony przez pakiet Homebrew o nazwie "foo", to plik build/pkgs/PACKAGE/distros/homebrew.txt powinien zawierać jeden wiersz "foo".

Testy Własne Pakietów (spkg-check.in)

Plik spkg-check.in jest opcjonalnym, ale wysoce zalecanym szablonem skryptu do uruchamiania testów własnych pakietu. Format dla spkg-check jest taki sam jak dla spkg-build i spkg-install. Jest on uruchamiany po zbudowaniu i zainstalowaniu, jeśli ustawiona jest zmienna środowiskowa SAGE_CHECK, zgodnie z przewodnikiem instalacji SageMath.

Idealnie, upstream ma jakiś zestaw testów, który można uruchomić za pomocą standardowego celu make check. W takim przypadku, szablon skryptu spkg-check.in zawierałby po prostu:

cd src $MAKE check 

Pakiety Oparte na Pythonie

Pakiety oparte na Pythonie powinny deklarować $(PYTHON) jako zależność, a większość pakietów opartych na Pythonie będzie również miała $(PYTHON_TOOLCHAIN) jako zależność tylko porządkową, co zapewni, że podstawowe pakiety, takie jak pip i setuptools, są dostępne w czasie budowania pakietu.

Najlepszym sposobem instalacji normalnego pakietu opartego na Pythonie jest użycie pip, w którym to przypadku szablon skryptu spkg-install.in może składać się tylko z:

cd src && sdh_pip_install . 

Dla szablonów skryptów spkg-check.in należy używać python3 zamiast tylko python. Ścieżki są ustawiane przez system budowania SageMath, aby zapewnić uruchomienie poprawnej wersji Pythona.

Wersjonowanie Pakietów

Plik package-version.txt zawiera tylko wersję pakietu. Jeśli pakiet upstream pochodzi z archiwum FoO-1.3.tar.gz, to plik wersji pakietu zawierałby tylko 1.3. Jeśli pakiet upstream pochodzi z rewizji innej niż stabilna wersja, lub jeśli upstream nie ma numeru wersji, należy użyć daty utworzenia rewizji. Na przykład, pakiet database_stein_watkins o wersji 20110713 zawiera bazę danych z dnia 2011-07-13.

Jeśli zastosujesz jakiekolwiek łatki, lub jeśli dokonasz zmian w archiwum upstream (patrz Modifying third-party code poniżej), to powinieneś dodać .p0 do wersji, aby wskazać, że nie jest to niezmodyfikowany pakiet. Dodatkowo, za każdym razem, gdy dokonujesz zmian w pakiecie bez zmiany archiwum upstream (na przykład, dodajesz dodatkową łatkę lub poprawiasz coś w pliku spkg-install), powinieneś również dodać lub zwiększyć poziom łatki. Tak więc różne wersje wyglądałyby tak: 1.3, 1.3.p0, 1.3.p1, … Zmiana numeru wersji lub poziomu łatki spowoduje ponowną instalację pakietu, tak aby zmiany zostały uwzględnione.

Sumy Kontrolne i Nazwy Archiwów

Plik checksums.ini zawiera wzorzec nazwy pliku archiwum upstream (bez aktualnej wersji) i jego sumy kontrolne. Na przykład, jeśli upstream to $SAGE_ROOT/upstream/FoO-1.3.tar.gz, utwórz nowy plik $SAGE_ROOT/build/pkgs/foo/checksums.ini zawierający tylko:

tarball = FoO-VERSION.tar.gz 

SageMath wewnętrznie zastępuje podciąg VERSION zawartością pliku package-version.txt.

Podsumowanie

Instalacja pakietów w SageMath jest kluczowym elementem rozszerzania funkcjonalności tego potężnego oprogramowania. Zrozumienie struktury pakietów, typów pakietów, skryptów instalacyjnych i narzędzi pomocniczych jest niezbędne do skutecznego zarządzania pakietami i dostosowywania SageMath do specyficznych potrzeb. Dzięki temu przewodnikowi powinieneś być w stanie bez problemu instalować nowe pakiety i w pełni wykorzystać potencjał SageMath.

Jeśli chcesz poznać inne artykuły podobne do Instalacja Pakietów w SageMath: Przewodnik Krok po Kroku, możesz odwiedzić kategorię Rachunkowość.