Eksperymentalny Klient Gadu-Gadu (C) Copyright 2001-2007 Autorzy (pełna lista poniżej) LICENCJA Program jest udostępniony na zasadach licencji GPL v2, której treść załączono w pliku src/COPYING. Niektóre pliki mogą być objęte inną licencją zgodną z GPL v2. Fakt ten jest odnotowany na początku pliku. Wyjątkiem od licencji GPL v2 jest możliwość kompilacji, konsolidacji i używania programu z biblioteką OpenSSL autorstwa Projektu OpenSSL (The OpenSSL Project) dostępną pod adresem http://www.openssl.org/ Program ekg i biblioteka libgadu zostały napisane na podstawie informacji uzyskanych przez badanie pakietów wysyłanych między klientem a serwerem oraz od osób trzecich. Autorzy nie disasemblowali ani nie dekompilowali oryginalnego klienta. Projekt powstał przy użyciu darmowych i wolnodostępnych narzędzi. Gadu-Gadu jest zastrzeżonym znakiem towarowym Gadu-Gadu S.A. WYMAGANIA Do komunikacji z serwerami Gadu-Gadu program wymaga biblioteki libgadu, która jest udostępniona oddzielnie. Więcej informacji o tym jak ją pobrać i zainstalować, znajdziesz w pliku libgadu.txt Program domyślnie korzysta z biblioteki ncurses, więc powinny być zainstalowane odpowiednie pakiety zawierające bibliotekę oraz pliki nagłówkowe. Jeśli chcesz użyć starego interfejsu, do polecenia configure dodaj ,,--disable-ui-ncurses''. Interfejs ten wymaga zainstalowania biblioteki readline wraz z plikami nagłówkowymi. readline zwykle polega też na innych bibliotekach do obsługi terminala, jak np. libtermcap czy ncurses. Instalacja obu interfejsów naraz nie jest wskazana. Oczywiście niezbędny jest też zestaw narzędzi do kompilacji programów napisanych w języku C -- kompilator, preprocesor, linker, pliki nagłówkowe, biblioteki systemowe itd. Jeśli skrypt ./configure zgłosi jakieś błędy, skontaktuj się ze swoim administratorem. ekg powinien działać na większości systemów uniksowych, jak Linux, *BSD, SunOS, IRIX itp. lecz czasami przy dodawaniu nowych funkcji nie sposób sprawdzić ich zachowania na wszystkich popularnych systemach. W takim wypadku przydatne są informacje o błędach z dokładnym wskazaniem systemu i architektury. INSTALACJA Rozpakować poleceniem ,,tar zxvf ekg-XXX.tar.gz'' (gdzie XXX to wersja programu lub data wykonania snapshotu), wejść do utworzonego katalogu. Jeśli mamy uprawnienia administratora na danej maszynie, wywołujemy ,,./configure'', potem ,,make'' i z prawami roota ,,make install''. Jeśli chcemy zainstalować program w katalogu domowym, do polecenia configure dodajemy parametry ,,--prefix=$HOME/ekg --mandir=$HOME/ekg/share/man''. Po zainstalowaniu w ten sposób, program gotowy do uruchomienia będzie znajdował się w katalogu ekg/bin w katalogu domowym. Jeśli chcemy mieć możliwość używania poleceń ,,beeps_spk'' i ,,blink_leds'', służących m.in do manipulowania diodami LED na klawiaturze, należy przy uruchomieniu użyć parametru ,,--enable-ioctld''. Proste? Proste. Po pierwszym uruchomieniu ekg powie, jak go skonfigurować. UŻYCIE Jest na tyle intuicyjne, że nie powinno sprawić problemów (wszyscy betatesterzy poradzili sobie bez jakiejkolwiek dokumentacji). Interfejs jest wzorowany na irssi. Dopełnianie tabem jest dostępne w większości komend. Komendy można wywoływać skrótami, o ile są one jednoznaczne. Wysyłanie wiadomości komendą ,,msg'', otwarcie okna rozmowy komendą ,,query''. Informacje o rozmówcach ,,find'' w oknie rozmowy. Szukanie tą samą komendą, ale z różnymi parametrami. ,,help'' Twoim przyjacielem. Jeśli dana komenda ma różne opcje, pomaga ,,help <komenda>''. By wysłać kilkulinijkową wiadomość w interfejsie ncurses, wciśnij Ctrl-Enter. W readline zamiast treści wpisz ,,\'' (backslash) i zakończ linią z samą kropką (szczegóły poniżej, w rozdziale ,,KLAWIATURA''). Program można skonfigurować pod wieloma względami, a wszystkie możliwe ustawienia, które zmienia się poleceniem ,,set'', są opisane w pliku vars.txt. Pomoc dotyczącą poszczególnych ustawień można uzyskać także poprzez polecenie ,,help set <zmienna>''. Jeśli dana komenda przyjmuje ,,--parametr'', można użyć również skrótu ,,-p'', gdy nie powoduje to niejednoznaczności. Uwaga! Brana pod uwagę jest zwykle pierwsza litera, więc jeśli chcesz skrócić ,,list --gone'' do ,,list -g'', ekg potraktuje to jako ,,list --get''. Komendy można wysyłać także przez potok. By go uaktywnić, należy uruchomić ekg z parametrem ,,-c'' i ścieżką potoku. Ze względu na specyfikę potoków, wyniki poleceń wysyłane będą na terminal, na którym jest uruchomione ekg (tak jak normalnie). Pisać do potoku można tak jak do normalnego pliku (choćby poleceniem echo). Jeśli w linii poleceń shella podasz po nazwie programu i parametrach zaczynających się od myślnika coś jeszcze, to zostanie to zinterpretowane jako komenda wsadowa. ekg połączy się z serwerem, wykona tylko tę komendę i od razu wyjdzie. Jeśli na serwerze czekają na Ciebie jakieś wiadomości, to serwer je przyśle zaraz po połączeniu i w trybie wsadowym ekg wypisze je na terminal. Jeśli zamierzasz przekierować wyjście do /dev/null i nie masz włączonego logowania, wiadomości zginą bezpowrotnie. KLAWIATURA Jeśli nie masz doświadczenia w obsługiwaniu programów z emacsową filozofią obsługi klawiatury, oto lista obsługiwanych klawiszy: Up, Down przeglądanie historii poleceń Left, Right poruszanie się po aktualnej linii Ctrl-A, Home idź na początek linii Ctrl-B pogrubiona czcionka [3] Ctrl-D, Delete usuń znak pod kursorem Ctrl-H, Backspace usuń znak przed kursorem Ctrl-I, Tab dopełnianie Ctrl-K usuwa tekst od kursora do końca linii Ctrl-L czyszczenie/odświeżanie ekranu Ctrl-M, Enter zatwierdzenie linii Ctrl-Q odblokowanie terminala Ctrl-R kolor tekstu [3] Ctrl-S zablokowanie terminala Ctrl-T pochyła czcionka [3] Ctrl-V pozwala wpisać dowolny znak [2] Ctrl-U usunięcie aktualnej linii Ctrl-W, Alt-Backspace usunięcie słowa przed kursorem Ctrl-Y wklejenie ostatnio usuniętego bloku Ctrl-Z przeniesienie programu w tło Ctrl-_ podkreślona czcionka [3] Alt-B słowo do tyłu Alt-D usunięcie słowa za kursorem Alt-F słowo do przodu Alt-cyfra przełączenie do podanego okna F1 pomoc F2 krótka lista dostępnych i zajętych F12 lub Alt-` przełączenie do okna debugowania Lista ta obejmuje klawisze obsługiwane przed interfejs readline i ncurses, i nie zawiera kombinacji specyficznych dla tego pierwszego. Interfejs readline obsługuje również inne kombinacje klawiszy. Dokładna lista znajduje się w stronie manuala ,,readline'' w rozdziale ,,DEFAULT KEY BINDINGS''. Dodatkowo: Ctrl-D zamyka rozmowę i anuluje wprowadzanie wiadomości wielolinijkowej Interfejs ncurses obsługuje kilka dodatkowych kombinacji: Page Up, Page Down przewijanie ekranu Ctrl-F, Ctrl-G j.w. Alt-A przejdź do pierwszego aktywnego okna Alt-S przejdź do najstarszego aktywnego okna (okna, które najdłużej jest aktywne) Alt-N utwórz nowe okno Alt-K zamknij aktualne okno Alt-G ignoruj aktualnego rozmówcę Alt-Q do Alt-P przełącza do okna 11 do 20 Alt-Z przewijanie listy kontaktów w górę Alt-X przewijanie listy kontaktów w dół Ctrl-Fn przełącza do podanego okna (konsola FreeBSD) Ctrl-Enter przejście do trybu wielolinijkowego Ctrl-P poprzednie okno Ctrl-N kolejne okno F3 włącza lub wyłącza listę kontaktów [1] F4 kolejna grupa w liście kontaktów F11 wybór informacji w pasku statusu Po wejściu do trybu wielolinijkowego poruszamy się za pomocą kursorów i zatwierdzamy ponownym wciśnięciem Ctrl-Enter. By anulować, wciskamy Esc i czekamy chwilę. Jeśli kombinacja ta nie jest obsługiwana przez terminal, można używać Alt-Enter lub wcisnąć Esc i zaraz po nim Enter. Dodatkowo, określonym kombinacjom klawiszy można przypisać różne komendy za pomocą polecenia ,,bind''. Ze względu na niestandardowe zachowanie niektórych typów terminali, mogą wystąpić problemy z kombinacją Alt-Shift-O lub Alt-O przy włączonym Caps Locku. [1] Klawisz F3 zmienia wartość zmiennej ,,contacts''. Jeśli wartość tej zmiennej była równa 0, wciśnięcie klawisza zmienia jej wartość na 2. Jeśli była równa 1, kolejne wciśnięcia F3 będą zmieniały wartość z 1 na 0 i z 0 na 1. [2] Po wciśnięciu Ctrl-V należy wcisnąć klawisz, który chcemy wkleić. Dzięki temu możliwe jest wpisanie znaków typu Escape, Ctrl-L czy Ctrl-U. [3] W miejscu wciśnięcia klawisza pojawi się znak oznaczający kod klawisza w negatywie. By zmienić kolor tekstu, należy po Ctrl-R wpisać numer koloru od 0 do 15. PLIK KONFIGURACYJNY Kolejność ładowania plików konfiguracyjnych jest następująca: 1) /etc/ekg.conf (lub z innego katalogu wskazanego przez opcję --sysconfdir przekazaną skryptowi ./configure), 2) ~/.gg/config lub ~/.gg/<profil>/config, 3) /etc/ekg-override.conf Dzięki temu administrator może wymusić pewne opcje na klientach użytkowników, jak na przykład ,,server'' czy ,,proxy''. Globalne pliki konfiguracyjne można ignorować przez uruchomienie klienta z opcją ,,-N''. GDZIE SZUKAĆ POMOCY Dobra rada numer jeden: zanim zaczniesz narzekać, że czegoś nie ma, przeczytaj plik TODO. Dobra rada numer dwa: plik ULOTKA mówi, co znajduje się w którym pliku dokumentacji. Dobra rada numer trzy: zanim zaczniesz narzekać, że czegoś nie ma, poszukaj w pliku ChangeLog. Dobra rada numer cztery: jeśli jesteś nowym użytkownikiem, nie pytaj się, czy coś da się zrobić, albo że przydałoby się. Program jest rozwijany od kilku lat, wielu ludzi korzysta z niego na co dzień, więc większość ,,bajerów'', o których możesz pomyśleć, na pewno jest już w programie. WYSYŁANIE SMSÓW ekg korzysta z zewnętrznego programu do wysyłania smsów. Nie ma najmniejszego sensu dublowania tej funkcji, skoro i tak większość ma już zainstalowane odpowiednie skrypty/programy/cokolwiek. Wystarczy podać ścieżkę do takiego programu w zmiennej ,,sms_send_app''. Powinien przyjmować numer telefonu za pierwszy parametr i wiadomość za drugi. Ten ze strony http://ceti.pl/~miki/ spełnia podane wymagania. SYNTEZA MOWY ekg potrafi korzystać z zewnętrznej aplikacji do syntezy mowy, by odczytywać wszystko, co trafia na ekran. Wystarczy ustawić zmienną ,,speech_app'' na nazwę programu czytającego tekst z stdin. Jej ustawienie spowoduje również zmianę wyglądu programu, by wyświetlane komunikaty stały się łatwiejsze do wymówienia. Przykładowe ustawienia, gdy korzystamy z programu ,,powiedz'', to: set speech_app powiedz set make_window 0 set display_sent 0 set display_ack 3 Program ,,powiedz'' można pobrać z http://cvs.pld.org.pl/SOURCES/powiedz_0.2.tgz ZNANE PROBLEMY Jeśli nie możesz wpisywać polskich liter w interfejsie readline, dopisz do pliku /etc/inputrc lub ~/.inputrc następujące linie: set meta-flag on set convert-meta off set output-meta on ROZPOZNAWANIE PŁCI Krótka wersja: Jeśli ekg źle rozpoznaje płeć, wpisz imię do listy kontaktów. W większości przypadków pomoże. No tak, nie masz pojęcia, jak to zrobić? ,,list pseudonim -f imię''. Pomogło? Świetnie. Nie pomogło? Czytaj dalej. Długa wersja: Jedną z najbardziej kontrowersyjnych cech programu jest automatyczne rozpoznawanie płci na podstawie ostatniej litery imienia lub gdy jest ono nieznane, pseudonimu. Gdy ostatnią literą jest ,,a'', ekg uznaje, że dana osoba jest kobietą. Na przykład, jeśli Twój znajomy ma pseudonim ,,Kuba'', wpisz do listy kontaktów imię ,,Jakub''. Problemy mogą wystąpić z rzadko spotykanymi imionami typu Barnaba czy Mercedes. W takim wypadku należy do imienia dopisać (chociażby po ukośniku lub w nawiasie) literę ,,a'' dla kobiet lub inną niż ,,a'' dla mężczyzn. ZGŁASZANIE BŁĘDÓW Jeśli zauważysz jakiś błąd, sprawdź najnowszą wersję. Większość błędów jest poprawiana w ciągu jednego lub dwóch dni od chwili pojawienia się. Przy zgłaszaniu błędu zaznacz, w której wersji występuje. Nie pisz o sprawach, które są już wymienione w pliku TODO, bo doskonale wiemy, że coś trzeba poprawić. Zaznacz, co to za system, jaka dystrybucja, jaka wersja. Jeśli błąd jest powtarzalny i związany z siecią, przejdź do okna debug i przyślij to, co zostaje tam wyświetlone przed samym wystąpieniem błędu (zwykle ~20 linijek wystarczy). Możesz też skorzystać z ukrytego polecenia ,,_debug_dump'', które zapisze ostatnie linie z debug do pliku lub też przed uruchomieniem ekg wpisać nazwę pliku, do którego przekierowany będzie debug, do zmiennej systemowej ,,EKG_DEBUG''. Jeśli program powoduje naruszenie ochrony pamięci i powstaje plik ,,core'', postępuj zgodnie z instrukcjami pokazanymi na ekranie -- uruchom ,,gdb ekg core'', przyślij to, co się pojawi. Potem wydaj polecenie ,,bt'' i jego wynik również załącz do listu. Jeśli błąd może mieć coś wspólnego z siecią, wyślij utworzony plik ,,debug''. Jeśli program się zawiesi, nie reaguje na nic i zajmuje 100% czasu procesora, w innym oknie terminala wydaj polecenie ,,strace -p <pid>'', gdzie <pid> to numer procesu ekg (uzyskasz go poleceniem ,,ps x'') i wyślij ostatnie 20 linii. Informację o błędzie należy przesyłać na listę ekg-users (nie trzeba się na nią zapisywać, szczegóły niżej), ponieważ w ten sposób dostaną ją (prawie) wszyscy autorzy kodu. Możliwe też, że któryś z użytkowników natknął się na to samo i wie, jak sobie z tym poradzić. ŹRÓDŁA Snapshoty kodu są dostępne pod adresem http://ekg.chmurka.net/ Jeśli nie wystąpi żadne trzęsienie ziemi, brak prądu ani barykady na drogach, powinny być robione co 24 godziny, wieczorem. Poza snapshotami, co jakiś czas będą umieszczane na serwerze kolejne wersje klienta. Ze względu na organizację prac nad programem, w praktyce nie będą się one różnić znacznie od snapshotów. Przed wydaniem każdej wersji wstrzymane będzie dodawanie nowych opcji, by skupić się na usuwaniu błędów. Poza tym, ułatwi to pracę niektórym osobom zajmującym się tworzeniem paczek dla dystrybucji -- zamiast uaktualniania ich do nowych snapshotów, będą miały możliwość pakowania ,,stabilnych'' wersji. Część kodu jest ładnie udokumentowana, część nie. Komentarze czasami są bardzo głupie, ale jeśli się do trzeciej rano siedzi nad dziwnym segfaultem, ciężko się pohamować. Jeśli napiszesz jakiegokolwiek klienta, frontend czy coś takiego, daj znać -- odnośnik do projektu zostanie umieszczony na stronie ekg. LISTA DYSKUSYJNA Istnieje lista dyskusyjna dla użytkowników ekg o adresie ekg-users@lists.ziew.org. Aby się zapisać, należy wejść na stronę o adresie: http://lists.ziew.org/mailman/listinfo/ekg-users oraz postępować według instrukcji tam zawartych. AUTORZY Wymienione osoby miały mniejszy lub większy wpływ na rozwój biblioteki i klienta. Niektórzy pisali kod, pomagali analizować protokół, testowali na różnych systemach, inni podsyłali patche i bugreporty. Jeśli ktoś został pominięty, niech da znać. W każdym razie za to, jak wygląda ekg, odpowiedzialni są (w porządku alfabetycznym): Marek Antoniak <kfazi@kfazi.polnet.trzepak.pl> Wojciech Bojdoł <wojboj@htcon.pl> Kamil Brzeziński <carnil@fordon.pl> Tomasz Chiliński <chilek@chilan.com> Marcin Chojnowski <martii@obgyn.edu.pl> Piotr Domagalski <szalik@szalik.net> Michał Dorociński <zwierzak@venus.ci.uw.edu.pl> Tomasz Dudzisz <eileen@ds1.agh.edu.pl> Piotr Figiel <feeg@psychodelic.org> Rafał Florek <raf@regionet.regionet.pl> Artur Gawryszczak <gawrysz@camk.edu.pl> Stanisław Gurgacz <sgurgacz@o2.pl> Darek Jackowski <ascent@home.pl> Rafał Janiczek <jojo@dexter.zst.bytom.pl> Dawid Jarosz <dawjar@poczta.onet.pl> Tomasz Jarzynka <tomee@cpi.pl> Kuba Jermak <kooba@irc.pl> Jarosław Kamper <jack@jack.eu.org> Asia Kaniewska <kj_asia@wp.pl> Wojtek Kaniewski <wojtekka@irc.pl> Maciej Korzeń <maciekk@linux.sky.pl> Paweł Kot <pkot@linuxnews.pl> Marek Kozina <klith@irc.pl> Adam Kruszewski <phantom@linux.bydg.org> Piotr Kupisiewicz <deli@rzepaknet.us> Adam Ludwikowski <adam.ludwikowski@wp.pl> Jakub Martyński <jakub@ceto.pl> Paweł Maziarz <drg@go2.pl> Marcin Mikuła <meecash@meecash.prv.pl> Arkadiusz Miśkiewicz <arekm@pld-linux.org> Jacek Osiecki <joshua@ceti.pl> Robert Osowiecki <magic.robson@rassun.art.pl> Adam Osuchowski <adwol@polsl.gliwice.pl> Marcin Owsiany <porridge@debian.org> Maurycy Pawłowski <maurycy@kocham.cie.gov.pl> Artur Pietruk <arturp@plukwa.net> Jacek Pospychała <tri10o@bsod.org> Paweł Pruszkowski <arim@botrm.org> Jacek Rembisz <jr178783@zodiac.mimuw.edu.pl> Rafal Roszak <rmrmg@wp.pl> Krzysztof Składzień <coxoc@coxoc.org> Rafał Skoczylas <nils@secprog.org> Adrian Smarzewski <adrians@aska.com.pl> Walerian Sokołowski <ws171913@yahoo.com> Piotr Stolc <socrtp@sedez.iq.pl> Tomasz Torcz <zdzichu@irc.pl> Leszek Urbański <tygrys@moo.pl> Robert J. Woźny <speedy@ziew.org> Krzysztof Wójtowicz <misiolek@misiolki.prv.pl> Adam Wysocki <gophi@ekg.chmurka.net> Piotr Wysocki <wysek@linux.bydg.org> $Id$