[Poradnik]Wstęp dla programisty - czyli jak zacząć rozwijać Mirande NG

[wsx22]

Wstęp dla programisty - czyli jak zacząć rozwijać komunikator Miranda NG

• Źródła Mirandy
• System zgłaszania błędów
• Pobranie źródeł
• Struktura źródeł
• Jak zacząć tworzyć swój własny plugin
• Kompilacja kodu
• Jak debugować kod Mirandy

1. Źródła Mirandy

Kod źródłowy Mirandy oraz wtyczek z nią rozpowszechnianych znajduje się na oficjalnym repozytorium SVN pod adresem http://svn.miranda-ng.org/main/trunk
Cały kod źródłowy Mirandy, kod wszystkich wtyczek a także pliki tłumaczeń langpack są utrzymywane w jednym SVN

Zmiany w tym kodzie można śledzić pod adresem http://trac.miranda-ng.org/timeline

W miarę potrzeb tworzone są również gałęzie rozwojowe kodu (http://svn.miranda-ng.org/main/branches).

2. System zgłaszania błędów

Błędy wykryte w Mirandzie oraz we wtyczkach z nią rozpowszechnianych można przeglądać i zgłaszać na stronie http://trac.miranda-ng.org/report

Procedura zgłaszania błędów opisana jest na stronie wiki http://wiki.miranda-ng.org/index.php?title=Strona_g%C5%82%C3%B3wna w sekcji "Dodatkowa pomoc"

3. Pobranie źródeł

Źródła Mirandy przechowywane są w systemie kontroli wersji Subversion SVN.
Do  ściągnięcia aktualnych źródeł na lokalny dysk polecam windowsowego  klienta SVN - Tortoise SVN
Adres URL repozytorium to: http://svn.miranda-ng.org/main/trunk

4. Struktura źródeł

- Katalog \include

Katalogiem który najbardziej interesuje twórców wtyczek jest katalog /include
http://trac.miranda-ng.org/browser/trunk/include
zawarte są tam pliki nagłówkowe API Mirandy czyli definicje struktur i funkcji z których można korzystać w swoich wtyczkach.

W chwili obecnej jedyną aktualną dokumentacją API Mirandy są komentarze umieszczone plikach nagłówkowe w katalogu include.

W podkatalogu \include\delphi znajdują się pliki *.inc dla środowiska Delphi, co umożliwia tworzenie wtyczek w tym środowisku.

- Katalog \plugins
Kody źródłowe pluginów Mirandy.
\plugins\!Deprecated - wtyczki których rozwój nie jest już kontynuowany.
\plugins\!NotAdopted - wtyczki których kod czeka na przeniesienie do Mirandy NG

- Katalog \protocols
Kody źródłowe pluginów Mirandy które odpowiadają za wsparcie protokołów.

- Katalogi \bin10 \bin11 \bin12

W katalogach tych znajdują się pliki solucji i zbiorcze pliki projektów dla środowiska Microsoft Visual C++
Dostępne są konfiguracje dla wersji:
\bin10   -   Microsoft  C++ 2010      (pliki projektów *_10.vcxproj)
\bin11   -   Microsoft Visual C++ 2012       (pliki projektów *_11.vcxproj)
\bin12   -   Microsoft Visual C++ 2013      (pliki projektów *_12.vcxproj)

Podkatalog \binXX\lib zawiera pliki .lib Mirandy, i ten katalog musimy wskazać w konfiguracji linkera w swoim projekcie.

- Katalog \src
Kod źródłowy core Mirandy

- Katalog \build
Skrypty do budowy core Mirandy

- Katalog \tools
Narzędzia wspierające budowanie, instalator Mirandy

- Katalog \docs
Dokumenty

- Katalog \langpacks
Pliki tłumaczeń langpack

- Katalog ..\boost
Katalog z bibliotekami boost. Nie ma go na SVN ale zakłada się że jest dostępny w tym samym miejscu co folder \trunk\

5. Jak zacząć tworzyć swój własny plugin

Do  rozwoju wtyczek wykorzystujemy język c++ (lub Delphi), funkcje Mirandy z katalogu include, funkcje Windows API (winapi) oraz ewentualnie zewnętrzne biblioteki c++ (np. boost)

Polecam skorzystanie z darmowej wersji środowiska: Visual Studio Express 2013 for Windows Desktop (najnowsza) lub Visual C++ 2010 Express (starsza)
zdostępne na stronie http://www.visualstudio.com/pl-pl/downloads/download-visual-studio-vs#DownloadFamilies_4

Najprostsza wtyczka z zaimplementowanym interfejsem wymaganym przez Mirandę NG dostępna jest w katalogu \plugins\testplugin

6. Kompilacja kodu

Standardowy projekt pluginu zawiera 4 konfiguracje
Debug Win32, Debug x64, Release Win32, Release x64
wersje debug - wersje przeznaczone do testowania (więcej informacji dla debuggera, zdefiniowana flaga prekompilatora _DEBUG )
wersje release - wersje przeznaczone do rozpowszechnienia (bardziej zoptymalizowane, mniejszy rozmiar)
wersje Win32 - wersje 32 bitowe
wersje x64 - wersje 64 bitowe

Aby skompilować projekt w wybranej wersji wybieramy: Build project

Wynik kompilacji pluginy domyślnie zapisywany jest w katalogu \binXX\<konfiguracja>\Plugins
Wygenerowane zostaną pliki <nazwa_projektu>.dll (plugin) oraz <nazwa_projektu>.pdb (informacje przydatne przy debuggowaniu i generowaniu crashlog)

Dobrze jest mieć osobny folder z czystą instalacją Mirandy do którego można przenieść i testować plugin.

7. Jak debugować kod Mirandy

Debugowanie kodu jest najwygodniejszą metodą poznawania kodu i szukania w nim błędów.

Zaczynamy od zdefiniowania tzw. punktów wstrzymania (breakpoints) w kodzie
Na interesującej nas linii kodu klikamy: Prawoklik > Breakpoint > Insert Breakpoint
Linia zostanie oznaczona czerwoną kropką, gdy któryś z wątków procesu który debugujemy dojdzie do tak oznaczonej linii kodu,
jego wykonywanie zostanie wstrzymane na tej linii, a w oknie Visual  Studio będzie można podglądnąć wiele informacji o nim (np. aktualne wartości zmiennych)

Aby zacząć debugować nasz projekt potrzebujemy skompilowanego (najlepiej w konfiguracji debug) pliku .dll oraz odpowiadającego mu pliku .pdb
Pliki kopiujemy do testowej instalacji Mirandy do katalogu /plugins i uruchamiamy Mirandę.
Następnie w Visual Studio podpinamy się debuggerem klikając na Debug >  Attach   to process...  i wskazując na proces naszej Mirandy
(Warto mieć w Mirandzie więcej niż jeden profil, wtedy po jej uruchomieniu wyświetlany jest manager profili, mamy wtedy czas na podpięcie się debuggerem przed startem pluginu)

[AL|EN]

GitHub: https://github.com/miranda-ng/miranda-ng