Organizacja API MorphOS-a

Grzegorz Kraszewski

---

Ten artykuł w innych językach: angielski

API (interfejs programisty aplikacji) systemu operacyjnego składa się zazwyczaj z tysięcy funkcji. MorphOS nie jest tu wyjątkiem. Jego kernel nie jest jednak monolityczny, API jest funkcjonalnie i fizycznie podzielone na biblioteki. Tylko kilka największych bibliotek zawiera więcej niż 50 funkcji. Zestaw najważniejszych bibliotek znajduje się w startowym pliku kernela (ang. boot image). Pozostałe umieszczone są na partycji systemowej dysku w katalogu MOSSYS:Libs (biblioteki dostarczane z systemem) i SYS:Libs (zewnętrzne biblioteki dodatkowe). Biblioteki znajdujące się na dysku są ładowane do pamięci na żądanie. Wszystkie te biblioteki są współdzielone, co oznacza, że wszystkie procesy używające danej biblioteki wykonują ten sam kod, umieszczony w pamięci jednokrotnie.

Przegląd najważniejszych bibliotek

Dystrybucja MorphOS-a zawiera ponad 100 różnych bibliotek. Oczywiście poniżej wymienione są tylko najważniejsze. Opis pozostałych można znaleźć w dokumentacji znajdującej się w SDK.

• exec.library, główna biblioteka systemu, tu znajdują się podstawowe elementy systemu takie jak zarządzanie procesami i zarządzanie pamięcią, ładowanie innych bibliotek, kontrola stanu systemu i tak dalej. Jako jedyna biblioteka jest zawsze otwarta i nie da się jej zamknąć.

• dos.library, odpowiada za operacje wejścia/wyjścia na plikach i innych urządzeniach (np. konsola tekstowa). Jest interfejsem do bardziej złożonych funkcji systemów plików (np. przeszukiwanie katalogów). Współdziała z exec.library przy tworzeniu procesów. Zawiera podstawowe funkcje zegara czasu rzeczywistego.

• graphics.library, zawiera niskopoziomowe funkcje graficzne, np. rysowanie pojedynczych pikseli i prostych figur geometrycznych, kopiowanie prostokątnych obszarów obrazu, przewijanie (scroll) itp. Wiele programów nie korzysta z niej bezpośrednio.

• intuition.library, zarządza podstawowymi obiektami interfejsu użytkownika, takimi jak ekrany i okna. Zajmuje się obsługą urządzeń wejściowych (mysz, klawiatura i inne). Zawiera w sobie BOOPSI (Basic Object Oriented System for Intuition), który jest bazą dla niezależnego od języka programowania obiektowego. Baza ta jest używana przez wiele innych komponentów systemu.

• muimaster.library, jest głównym interfejsem MUI (Magic User Interface) – podstawowej wysokopoziomowej biblioteki do tworzenia graficznego interfejsu użytkownika programów. MUI jest rozwinięciem BOOPSI, daje programiście kompletny szkielet do programowania obiektowego sterowanego zdarzeniami i dostarcza bogaty zestaw gadżetów (kontrolek).

• locale.library, służy do tworzenia wielojęzycznych wersji programów. Oprócz umożliwienia prostej lokalizacji interfejsu użytkownika, pozwala również programom na pobranie od systemu ogólnych danych specyficznych dla kraju i języka użytkownika (np. waluta, format daty, strefa czasowa, grupowanie cyfr w dużych liczbach itp.)

• bsdsocket.library, jest biblioteką obsługującą protokół TCP/IP, kompatybilną z interfejsem BDS sockets. Co ciekawe biblioteka ta nie znajduje się ani w kernelu ani na dysku – jest tworzona dynamicznie w pamięci przez stos TCP/IP.

Jak używać bibliotek w programach

Najczęściej użycie biblioteki w programie jest praktycznie automatyczne. Jedyna rzecz, jaką trzeba zrobić, to zainkludowanie głównego pliku nagłówkowego biblioteki, którego nazwa tworzona jest według schematu <proto/[nazwa biblioteki].h>, na przykład <proto/exec.h>, <proto/muimaster.h> i tak dalej. Otwarcie i zamknięcie biblioteki jest wykonywane automatycznie w kodzie startowym, pochodzącym z libnix-a albo ixemul.library. W programie można więc po prostu używać funkcji danej biblioteki.

Kilka największych bibliotek posiada własne podkatalogi w drzewie plików nagłówkowych systemu. Przykładami mogą tu być exec.library, dos.library, czy graphics.library. Pliki nagłówkowe w tych katalogach zawierają definicje stałych, struktur danych, atrybutów itp. podzielone według zastosowania. Inkludowanie tych plików w kodzie programu uzależnione jest od tego, które funkcje biblioteki są wykorzystane w programie. Przykładowo używając funkcji alokacji pamięci z exec.library powinniśmy zainkludować plik <exec/memory.h>.

Inne biblioteki mogą posiadać pojedynczy plik nagłówkowy w katalogu libraries. Na przykład <libraries/locale.h> lub <libraries/mui.h> (ten drugi przykład pokazuje małą niekonsekwencję w nazewnictwie...). Ten plik może być automatycznie inkludowany z bazowego proto, ale czasem musi być inkludowany ręcznie w kodzie programu.

W kilku przypadkach automatyczna obsługa bibliotek nie działa, albo nie można z niej skorzystać:

• Dodatkowe biblioteki pisane przez niezależnych programistów. Większość z nich nie jest dodana do listy bibliotek otwieranych automatycznie.
• Program korzystający z własnego kodu startowego (linkowany z opcją −nostartfiles).
• Biblioteki otwierane w podprocesie.
• Biblioteki otwierane w programie dynamicznie na żądanie.
• Baza biblioteki zdefiniowana w kodzie programu. W tym przypadku funkcja automatycznego otwierania jest wyłączana dla tej konkretnej biblioteki.

W powyższych przypadkach biblioteka musi być otwarta i zamknięta ręcznie.

Ręczne otwieranie i zamykanie bibliotek

While not as convenient as automatic handling, manual opening and closing of libraries is not very complicated. A library base variable has to be defined, then two functions from exec.library: OpenLibrary() and CloseLibrary() have to be used.

The library base is defined in its proto file (the main header) as a global variable. It is a pointer to a Library structure, which should be treated as an opaque pointer. The result returned by OpenLibrary() should be placed in the library base before any function of the library is called. Then, when the library is no longer needed, it should be closed with CloseLibrary() using its base as the argument. The layout for using the hypothetical foobar.library is as follows:

/* inside <proto/foobar.h> */

struct Library *FoobarBase;

/* inside application */

#include <proto/foobar.h>

if (FoobarBase = OpenLibrary((STRPTR)"foobar.library", 7))

{

  /* use library functions here */

  CloseLibrary(FoobarBase);

}

The OpenLibrary() call takes two parameters. The first one is just the name of the library to be opened. It is only the name, without path. MorphOS searches a few locations for the library in the following order:

• MOSSYS:Libs/
• LIBS:
• current directory of the application
• PROGDIR:Libs/

In the fourth path PROGDIR: is an automatic assign pointing to the directory containing the application executable.

The second parameter of OpenLibrary() is the minimum required version. Zero here opens any version, any positive number means "this version or higher". There is no straightforward way for requesting a particular version of a library. It can be noticed that this approach only works if newer versions of a library are always backward compatible with older ones. On the other hand it avoids having multiple versions of the same library in the system, which is a common problem with Linux shared objects.

The value returned by OpenLibrary() should be always checked against NULL. Even a library built into the boot image may fail to open (because of a memory shortage for example, or having too low a version). Printing some error message in case of a fail is definitely a good idea.

Every successful OpenLibrary() call must be matched with CloseLibrary(). Resource leak is created otherwise.

There are two special cases for manual library opening and closing: exec.library and dos.library. The first one is always open and cannot be closed, as stated above. The library base for it (named SysBase) is defined and initialized in the startup code. If declared manually in an application's source code, it should be declared as an extern. The dos.library is opened and closed as with any other library, but because the startup code needs it, the DOSBase is already defined and initialized there. As a result the application does not need to open dos.library before using it. If declared in an application, DOSBase should be an extern too.

As with the Amiga historical heritage, some of the most important library bases (SysBase, DOSBase, IntuitionBase, GfxBase and a few more) are not defined as struct Library* but as pointers to library specific structures. Direct poking of these structures was unavoidable in early AmigaOS versions. In MorphOS it is neither needed nor recommended. One can avoid the above definitions (which forces unnecessary typecasting in OpenLibrary() and CloseLibrary()) by #defining __NOLIBBASE__ symbol before including proto files. This disables library bases definitions. All bases can (and must) be then explicitly defined in the code as pointers to struct Library.

Also for traditional reasons, names of some library bases do not follow the [Libname]Base scheme. The most important deviations are: SysBase for exec.library, DOSBase for dos.library (capitalization), GfxBase for graphics.library, MUIMasterBase for muimaster.library (capitalization), CyberGfxBase for cybergraphics.library. In any case the base name can be checked by looking at the library proto header.

Using the proper base name is very important, as it is used as an implicit argument in all the calls of library functions.