MorphOS i GitHub (2022)
© TDolphin 2022
Ostatnia aktualizacja: 14.12.2022
MorphOS i GitHub
Wymagania:
MorphOS SDK (https://www.morphos-team.net/downloads)
przeglądarka Wayfarer (https://wayfarer.icu/)
Pomocne linki:
Opisany tutorial dotyczy stanu na jesień 2022, zarówno w kwestii wersji MorphOS (3.17), MorphOS SDK (3.16), Wayfarer (4.x) jak i samego GitHuba.
1. System kontroli wersji
Cytując wikipedię: System kontroli wersji (ang. version/revision control system) - oprogramowanie służące do śledzenia zmian głównie w kodzie źródłowym oraz pomocy programistom w łączeniu zmian dokonanych w plikach przez wiele osób w różnym czasie.
Tak bardzo upraszczając i nieco łopatologicznie, taki system pozwoli nam automatycznie posiadać kopie kolejnych wersji tworzonego przez nas oprogramowania. Co znowu ułatwi nam na szybkie sprawdzenie na przykład, jakie zmiany spowodowały pojawieni się konkretnego błędu od którejś tam wersji. Również bez problemu pozwoli nam “cofnąć” źródła do konkretnej wersji.
Od dobrych kilku lat jednym z najpopularniejszych systemów kontroli wersji jest git. W sieci mamy kilka serwisów hostingowych które pozwalają nam zarządzać naszymi repozytoriami z kodem który mamy pod kontrolą gita, są to serwisy takie jak GitHub, GitLab czy SourceFroge. Korzystając z takich serwisów zyskujemy dodatkowo kopię bezpieczeństwa naszej pracy.
W naszym wypadku zajmiemy się integracją i podstawowym korzystaniem z GitHuba, który nie tylko jest miejscem trzymania naszego kodu (repozytorium z historią), ale jest też serwisem który posiada BugTracker’a, pozwala publikować nasze repozytoria (public repositories) jak i trzymać je jako prywatne (private repositories). Możemy również udzielać się w innych publicznych repozytoriach poprawiając błędy, dodając nowe funkcjonalności, czy też po prostu zgłaszając błędy itp.
2. Zakładamy konto na GitHubie
Do aktywnej pracy z GitHubem potrzebne jest nam konto. Bez niego możemy jedynie biernie przyglądać publiczne repozytoria (jednak z możliwością klonowania ich, etc). Nam jednak zależy na aktywnym korzystaniu w zakresie pracy nad własnymi prywatnymi lub też publicznymi projektami.
Strona SignUp do zakładania konta jest dostępna z głównej strony GitHuba, jednak jest ona dla nas niezbyt użyteczna ponieważ została napisana w ten sposób, że skutecznie konsumuje CPU, powodując że na maszynach z procesorami pokroju G4@1.42GHz jest przeraźliwie wolna, ale co ciekawe na kilkuletnich PC (np. z Intel Core i5-4310U @ 2.0GHz) z aktualną przeglądarką Chrome/Firefox strona jest jakoś używalna ale jej responsywność i procesorożerność pozostawia wiele do życzenia.
Jest jednak inne wyjście niż wchodzenie na tak “ociężałą” stronę, bo jest dostępna jeszcze jedna zwykła i lżejsza strona do rejestracji pod adresem https://github.com/join i właśnie z niej skorzystamy.
Po wejściu na stronę wypełniamy podstawowe dane jak nazwa użytkownika (dopuszczalne są małe, duże litery i maksymalnie jeden znak minusa), wprowadzamy adres email, hasło. I na samym końcu jesteśmy weryfikowani za pomocą CAPTCHA.
Jeśli utworzenie konta przejdzie pomyślnie, zostaniemy przekierowani na stronę gdzie musimy wprowadzić kod potwierdzający, który mamy w wiadomości na skrzynce mailowej. Po wprowadzeniu poprawnego kodu, przejściu personalizacji (można pominąć), nasze konto na GitHubie jest w pełni aktywne i zostajemy przekierowani na naszą stronę domową w GitHubie.
3. Dodatkowe ustawienia konta
Po utworzeniu konta warto dokonać pewnych zmian w jego ustawieniach. Takich jak publiczna nazwa użytkownika, obrazek profilowy, URL własnej strony, domyślna nazwa głównego brancha (główna gałąź projektu), podwójnej autentykacji (2FA), motyw kolorystyczny etc.
Domyślna nazwa głównego brancha
Od pewnego czasu słowo main jest domyślną nazwa głównego brancha dla każdego nowego repozytorium. Wcześniej główny branch w przypadku gita zwyczajowo nazywał się master, jednak GitHub postanowił być “politycznie poprawny” i źle kojarząca się nazwa została zmieniona właśnie na main. Niektórzy są jednak przyzwyczajeni do nazwy master i taką chcieli by mieć, lub też użytkownicy svn’a chcieli by mieć nazwę trunk, która zwyczajowo oznaczała główną gałąź. Można to zrobić poprzez Settings dostępnym w rozwijanym menu (prawy górny róg z ikonką użytkownika). A następnie na stronie Settings wybierając z lewego menu Repositories.
Na stronie ustawień repozytoriów można ustawić odpowiadającą nam nazwę dla głównego brancha.
4. Nowe repozytorium
Klikając w ikonkę GitHuba 
w prawym górnym rogu wracamy na stronę domową naszego konta, gdzie wybierając Create Repository tworzymy nasze pierwsze (i nowe) repozytorium.
Na stronie tworzenia repozytorium podajemy jego nazwę (Repository name), krótki opcjonalny opis (Description). Decydujemy czy repozytorium ma być publiczne czy prywatne. Na ten moment tworzymy nasze prywatne więc wybieramy Private.
Dobrze też jest zaznaczyć aby został dodany plik tzw. “Czytaj to” (Add a README file). Dobrze też jest dodać od razu plik .gitigniore w którym zdefiniowane są reguły według których git będzie pomijał pewne pliki i nie będzie uwzględniał ich w kontroli wersji, np. pliki typu object (z rozszerzeniem .o) powstające przy kompilacji programów napisanych w C/C++. W naszym przykładowym nowym repozytorium wybierzemy szablon pliku .gitignore dla języka C.
Po wybraniu Create repository lądujemy od razu na stronie głównej naszego nowego repozytorium. Gdzie jak widać nazwa głównego brancha jest master, jest w nim jeden commit o tytule “Initial commit”. A jedynymi plikami w repozytorium są .gitignore i wstępnie wypełniony README.md (plik tekstowy w formacie Markdown https://www.markdownguide.org/basic-syntax/).
5. Klonowanie repozytorium
5.1 Za pomocą HTTPS, … czy to jeszcze działa?
Będąc na stronie repozytorium, klikamy na przycisk Code, który pokazuje nam kilka opcji klonowania repozytorium, pierwszą z nich jest klonowanie za pomocą HTTPS. Klikamy w ikonę kopiowania urla (po lewej stronie) do schowka. I przechodzimy do shella (Shell) pod MorphOSem.
W shellu przechodzimy do katalogu gdzie będziemy chcieli sklonować nasze repozytorium. I następnie w wywołujemy gita z opcją klonowania wraz z adresem repozytorium (git clone <url>). W moim przypadku jest to:
git clone https://github.com/PPA-user/ppa.git
Po czym musimy wprowadzić Username (nasz adres email) i Password. U mnie w trakcie wprowadzania adresu email nie widać co wprowadzamy, nie wiem czy to taka przypadłość, akurat na MorphOSie czy samego gita, niemniej uprzedzam, aby się nie zdziwić. Nasz Username pojawi się dopiero poniżej w linijce podawania hasła. Oczywiście hasło jak najbardziej niewidoczne w trakcie wpisywania.
Jak widzimy próba klonowania za pomocą https i uwierzytelnienia tylko poprzez nazwą użytkownika i hasło nie powiodła się, ponieważ taki sposób autentykacji został usunięty na GitHubie już jakiś czas temu. Co możemy zrobić w takiej sytuacji? Otóż zgodnie z informacjami na stronach pomocy GitHuba, aby korzystać z HTTPSa należy utworzyć tzw Personal access token.
Zróbmy to. Wracamy do przeglądarki i za pomocą menu przechodzimy na stronę Settings, gdzie z lewego menu (na samym dole) wybieramy opcję <> Developer setting. Po drodze prawdopodobnie pojawi się strona aby potwierdzić dostęp hasłem, ta strona może czasami się pojawiać w zależności w jakie ustawienia wchodzimy. I tak na kolejnej stronie rozwijamy opcję z lewego menu Personal access tokens, z którego wybieramy Tokens (classic). Pojawia nam się kolejna strona na której wywołujemy z menu Generate new token pod opcję Generate new token (classic).
Definiując nowy token podajemy jego nazwę, czyli przykładowo, że jest przeznaczony dla naszej maszyny MorphOS-iBook-G4, następnie poniżej podajemy czas życia tokenu. Zalecane przez GitHub jest, aby nie tworzyć tokenów z nieograniczonym czasem życia. Ostatnią najobszerniejszą opcją jest zakres dostępowy dla tokenu, w naszym wypadku wystarczy zaznaczyć repo (pełny dostęp do prywatnych repozytoriów), co automatycznie spowoduje zaznaczenie również pod opcji.
Pozostaje już tylko wygenerować token na podstawie naszych ustawień, przyciskiem na końcu formularza. Po czym otrzymujemy stronę na której jest widoczny nasz wygenerowany token, musimy go sobie skopiować do schowka (znowu za pomocą ikonki kopiowania).
Następnie wracamy do shella i ponownie uruchamiamy tą samą komendę do klonowania co poprzednio, ale tym razem zamiast naszego hasła do GitHuba wklejamy skopiowany token. I gotowe, po zatwierdzeniu nasze repozytorium sklonowało się i mamy je w podkatalogu o nazwie takiej samej jak nazwa repozytorium, w naszym wypadku jest to katalog ppa.
Niestety Token nie zostaje zapamiętany i przy użyciu komend gita które odwołują się do zdalnego repozytorium, czyli np. komendy git push, git pull etc. Musimy za każdym razem podawać nasz Username i Password (czyli nasz token). Zatem jesteśmy zmuszeniu do zapisania sobie tokenu w jakimś pliku lokalnym pliku tekstowym.
5.2. Za pomocą SSH
Innym i zalecanym w naszej sytuacji sposobem autentykacji z GitHubem jest korzystanie z SSH, czyli korzystania z naszego klucza publicznego. Pierwszą rzecz którą musimy zrobić to utworzenie takiego klucza (w parze z kluczem prywatnym) na naszej maszynie, zakładamy, że jeszcze ich nie mamy.
Tworzenie kluczy odbywa się z poziomu shella i komendy ssh-keygen, gdzie jednym z parametrów jest email, w moim przypadku komenda wygląda następująco:
ssh-keygen -t ed25519 -C ppa@tdolphin.org
Przy generacji zostaniemy zapytani o nazwę (i lokalizację) pliku w którym ma zostać zapisany klucz, będzie podany domyślny, (powinien to być katalog .ssh w naszym domowym katalogu, u mnie to jest System:Home/.ssh) oraz pojawi się prośba o hasło dla klucza.
Katalog domowy użytkownika definiuje się w MorphOS Preferences (menu Ambienta: Settings → System…).
Przy generacji klucza można się posiłkować opisem na samym GitHubie, gdzie jest wyjaśnione tworzenie klucza: https://docs.github.com/en/authentication/connecting-to-github-with-ssh.
Po wygenerowaniu pary kluczy, wracamy do GitHuba gdzie dodamy nasz klucz publiczny (to ten z rozszerzeniem .pub). Będąc na stronie repozytorium, klikamy na przycisk Code, wybieramy opcję SSH. Gdzie będzie komunikat o braku klucza SSH, więc wchodzimy w add new public key.
Lądujemy na stronie dodawania nowego klucza publicznego, którego wartość możemy skopiować z shella, możemy go wyświetlić za pomocą komendy:
cat Home/.ssh/id_ed25519.pub
Nadajemy nazwę nowemu kluczowi, a skopiowany klucz publiczny wklejamy do formularza i zatwierdzamy Add SSH key.
Zostaniemy również poproszeni o potwierdzenie operacji hasłem do GitHuba. I powinniśmy widzieć nasz klucz na liście.
Wracamy do naszego repozytorium i tym razem już nie ma komunikatu o braku klucza i możemy śmiało kopiować adres url repozytorium do schowka.
Przechodzimy do shella pod MorphOSem, przechodzimy do miejsca gdzie chcemy sklonować nasze repozytorium i wykonujemy komendę do klonowania (git clone). W moim przypadku jest to:
git clone git@github.com:PPA-user/ppa.git
Za pierwszym razem zostaniemy zapytani o potwierdzenie połączenia z github.com, odpowiadamy yes i github.com znajdzie się w tzw known hosts (Home:.ssh/known_hosts). Podajemy hasło do naszego klucza i repozytorium klonuje się do katalogu o nazwie tego repozytorium. Wchodzimy do tego katalogu gdzie możemy sprawdzić historię zmian za pomocą komendy git log.
Niestety jakiekolwiek operacje odwołujące się do serwera GitHuba wymagają ciągłego podawania hasła. Np. komenda do aktualizacji naszej lokalnej wersji repozytorium: git fetch. Przy której znowu musimy podać hasło.
Obecnie w MorphOSie brakuje permanetnego zapamiętania autentykacji ssh do zdalnego repozytorium. Niemniej istnieje możliwość w ramach działającej sesji MorphOSa utrzymywania autentykacji ssh. Służy do tego ssh-agent komenda z SDK. Z linii komend uruchamiamy ssh-agent z parametrem -D co spowoduje, że będzie działał w tle i nasłuchiwał:
ssh-agent -D
Po czym (już z nowego shella) musimy tylko dodać naszą autentykację, robimy to za pomocą komendy ssh-add z parametrem do naszego klucza prywatnego po czym proszeni jesteśmy o hasło:
ssh-add Home:.ssh/id_ed25519
Teraz jakiekolwiek odwołanie do repozytorium na GitHubie które zostało sklonowane z użyciem ssh nie będzie wymagało podania hasła. Ale tylko w ramach aktualnej sesji MorphOS’a, czyli do restartu systemu.
Uruchomienie agenta do ssh możemy sobie nieco zautomatyzować dodając odpowiednią linię do user-startup:
run < nil: > nil: ssh-agent -D
6. Istniejący projekt
Co mamy zrobić gdy mamy istniejący projekt i chcemy go wrzucić na GitHuba?
Pierwszą rzecz to tworzymy sobie według kroków wyżej odpowiednie repozytorium. Gdzie ustalamy nazwą i opcjonalnie wybieramy (lub nie) utworzenie pliku README i również opcjonalnie wybieramy utworzenie pliku .gitignore. Tak utworzone repozytorium klonujemy, również wg kroków wyżej.
Następnie do sklonowanego repozytorium kopiujemy cały nasz istniejący projekt, najlepiej tylko pliki które nie są tworzone np. w trakcie budowania, jak pliki typu #?.o, choć jeśli wybraliśmy przy tworzeniu repozytorium dodanie pliku .gitignore z odpowiednim szablonem (np. dla języka Ansi C) to pliki #?.o będą ignorowane (o czym już wcześniej było wspomniane).
Z poziomu shella będąc w katalogu z projektem wywołujemy komendę która dodaje wszystkie pliki (wraz z niepustymi podkatalogami, rekurencyjnie) do indeksu repozytorium (uwaga: na końcu jest kropka):
git add .
Przed zrobieniem właściwego commita (czyli zatwierdzenia zmian), sprawdzimy aktualny status zmian, który da listę plików które zostaną w naszym przypadku dodane:
git status
Zakładamy, że wszystko się zgadza, zatem zatwierdzamy nasze zmiany (commit) komendą git commit wraz z odpowiednim komentarzem do commita:
git commit -m “komentarz do commita”
W tym momencie dalej nasze zmiany w repozytorium mamy lokalnie, musimy je wypchnąć na zewnątrz do serwera GitHuba. Możemy to robić w dowolnym momencie mając np. kilka zmian:
git push
W moim przykładzie całość wyglądać następująco:
Możemy sobie sprawdzić historię naszych zmian w repozytorium (git log):
Po tych kilku komendach nasze repozytorium z projektem na GitHubie ma już “ręce i nogi” 🙂
7. Słowo na koniec
Możemy teraz kontynuować pracę nad naszym projektem korzystając całego wachlarza udogodnień które daje nam zarówno sam git jak i GitHub. Czyli pracy w zespole, na oddzielnych “branczach” (branch), wystawianiu PR’ów (pull request), posiadając bazę problemów, ficzerów itp. Ale o tym już może w innym tutorialu.
