XMake: Uniwersalny System Budowania Projektów z Managerem Pakietów

Intro

xmake jest wieloplatrofmowym narzędziem do budowania projektów napisanych w różnych językach oprogramowania o składni opartej na https://www.lua.org/. Podobnie jak CMake generuje narzędzia do budowania, z tą różnicą, że ma bardziej ludzką składnię. Ponadto przy pomocy xmake'a można zaimportować projekt CMake'a i innych popularnych systemów budowania. Kolejną zaletą narzędzia jest to, że posiada on wbudowany manager pakietów. Na swojej oficjalnej stronie chwalą się szybkością jak manager budowania Ninja, który słynie z szybkości.

W nieniejszym artykule skupię się na użyciu narzędzia xmake przez programistę C++. Mimo iż xmake jest wieloplatformowe tak bardzo, że działa nawet na mało popularnych systemach, to jednak pisząc ten artykuł używałem systemu Linux (dystrybucji opartej na Ubuntu).

Narzędzie to ma bardzo dopracowaną dokumentację, bardzo długi i obszerny tutorial jak zacząć, jak również przykłady. Mimo iż nie jest to tak popularne jak CMake, to zawiera bardzo dużo możliwości, których nie jestem w stanie przedstawić w artykule, skupiając się jedynie na wybranych pod ogólnego programistę C++.

Narzędzie ma bardzo duże możliwości, nie tylko budowania, ale też uruchamiania zbudowanego programu, jak również uruchamiania testów i znacznie, znacznie, znacznie więcej możliwości.

Instalacja

Narzędzie to instaluje się zależnie od platformy. Instrukcja znajduje się w oficjalnym tutorialu. Przykładowo dla dystrybucji opartej na Ubuntu instalacja odbywa się tak:
Z kolei na dystrybucjach opartych na Archu:

Aktualizacja

Zaletą tego narzędzie, jest fakt, że jest ono samo-aktualizujące przy pomocy wbudowanej komendy, przykładowo:

Integracja z IDE

Narzędzie posiada wtyczki do integracji z CLion, VScode, QT Creatora, czy edytor vim i innymi.

Używanie narzędzia xmake

Obecnie narzędzie wspiera projekty korzystające z następujących języków programowania:

• C++
• C
• Objective-C and Objective-C++
• Swift
• Assembly
• Golang
• Rust
• Dlang
• Fortran
• Cuda
• Zig
• Vala
• Pascal
• Nim

Narzędzie jest dość łatwe w użyciu. W swoim projekcie możemy dodać plik , lub skorzystać z możliwości wygenerowania projektu.

Generowanie projektu

Aby utworzyć projekt należy użyć komendy:

Dla powyższej komendy został wygenerowany następujący plik :

Możliwe jest wiele różnych szablonów projektów, m.in.:

• console
• shared
• static
• qt.widgetapp (tylko c++)

Jak widać  umożliwia generowanie projektów z wsparciem biblioteki QT (jest znacznie więcej opcji generacji), jak również do pewnych narzędzi programistycznych.
Listę szablonów można znaleźć wpisując:

Przykładowe używanie xmake

Załużmy, że mamy już gotowy projekt (może być wygenerowany powyższymi komendami), teraz czas na przykładowe komendy:

Budowanie projektu z xmake

Odbywa się to przez zawołanie po prostu:
Domyślnie pliki wynikowe zostaną umieszczone w katalogu

Jeśli potrzebujemy przebudować projekt możemy zawołać:

Uruchomienie programu przez xmake

Aby uruchomić jeden z celów (ang. target) wystarczy napisać:

a, jeśli mamy więcej projektów możemy łatwo wskazać docelowy:

Mamy też możliwość uruchomienia wszystkich celów:
Kolejną wygodą jest możliwość przekazania argumentów uruchomienia, które podajemy za nazwą targetu:


Czasami programista musi skorzystać z możliwości debugowania, co jest też możliwe przez narzędzie :

Czyszczenie zbudowanych plików

Łatwość w konfiguracji platformy

Łatwo możemy zmienić konfiguracje do budowania. Przykładowo aby zmienić tryb między debug/release piszemy:
Po zmianie konfiguracji po prostu budujemy ponownie projekt.

Możemy też w łatwy sposób skompilować projekt pod inną platformę, w tym celu zmieniamy konfigurację:

Więcej opcji konfiguracji możemy znaleźć w standardowym  dla podkomendy  czyli:

ale mamy też możliwość wejścia w konfiguracyjne menu, przez zawołanie:

Jego możliwości widać na obrazku: Warto wspomnieć, że można tworzyć własne opcje (ang. option), które można ustawiać z poziomu menu.

Wbudowane typy projektów

• Biblioteka statyczna
• Biblioteka dynamiczna
• Aplikacja konsolowa
• Moduły C++20
• Program korzystający z Cuda
• Aplikacja Qt
• WDK Driver (umdf/kmdf/wdm)
• Aplikacja WinSDK
• Aplikacja MFC
• Aplikacja iOS/MacOS (Support .metal)
• Framework and Bundle Program (iOS/MacOS)
• Moduły SWIG (Lua, python, ...)
• Moduły Luarocks
• Protobuf program
• Lex/yacc program

Oczywiście można również tworzyć własne typy.

Obsługiwane platformy dla xmake

Mamy możliwość skonfigurowania targetów na popularne platformy (pełna lista platform i możliwych konfiguracji):

• Windows
• macOS
• Linux
• *BSD
• Android
• iOS
• WatchOS
• AppleTVOS
• MSYS
• MinGW
• Cygwin
• Wasm
• Cross (cross-toolchains)

Również na różne architektury np.: , czy .

Możemy sprawdzić listę dostępnych narzędzi programistycznych (ang. toolchains):
Mamy też możliwość utworzyć własnego toolchaina, czy napisać składowe istniejącego (np. kompilator).

Zawartość pliku xmake.lua

Najprostrza zawartość pliku  wygląda w następujący sposób:

Dodatkowe możliwości konfiguracyjne

Dodajemy je pod źródłem np.:

Dodawanie plików po wzorcu

Dodawanie stałych czasu kompilacji (define)

Dodawanie ścieżki z nagłówkami

Instrukcje warunkowe

Dodawanie katalogu zawierającego pliki źródłowe do pod-projektu

Można też wskazać plik podprojektu:

Można też rekursywnie:

Włączenie wbudowanych funkcji, przykładowo:

Biblioteki do linkera

Aby podać ścieżki do linkera:

Systemowe flagi linkera

Flagi dla linkera

Opcja  jest po to, aby flaga nie została zignorowana. Na ogół o zignorowaniu flagi informuje nas xmake w formie warningu.

Flagi dla kompilatora C++

Dodatkowy kod podczas instalacji targetu

W powyższym kodzie obok pliku  potrzebujemy plik , który będzie zawierał kod w lua.

Dodatkowy kod podczas/po/przed_budowaniem/instalacją/uruchamianiem

Możliwości można łączyć:

Ustawianie opcji konfiguracyjnych dla projektów

Jest bardzo dużo możliwości (szczegóły w dokumentacji), tylko pierwszy argument opcji jest obowiązkowy, resztę można pominąć.
Opcja  służy do tego, żeby dana opcja była wyświetlona w menu konfiguracyjnym projektu.

Możliwość konfiguracji dla konkretnego systemu

W powyższym przykładzie sprawdzamy czy mamy do czynienia z Linuxem lub MacOS, wtedy dodawana jest dodatkowa flaga

Możliwość iterowania po liście

Wykonywanie skryptu po zakończonej kompilacji

Dodawanie zależności do projektu (o tym później)

Projekty zależne od siebie

W ramach jednego pliku  jest możliwe dodanie wielu projektów/targetów. Mamy możliwość połączyć je zależnościami:

Łączenie projektu w archiwum

Wyłączenie użycie ccache

jest ono domyślnie używane.
Oczywiście można też użyć komendy zamiast zmieniać pliku konfiguracyjnego:

Zmiana ustawień ostrzeżeń kompilacji (ang. warning)

Domyślnie nie są one wyświetlane, możemy je włączyć w ustawieniach:
a także komendą:

Możliwość wskazania zestawu narzędzi (ang. toolchain)

Możliwość tworzenia tasków

Czyli dodatkowych "komend", które można wywołać, które mogą mieć różne argumenty wykonywania. Coś na podobnym poziomie jak target, czy option. Jest to zagadnienie bardziej skomplikowane, dlatego odsyłam do dokumentacji.

Inne zależności zależne od typu projektu

Dla różnych typów projektu istnieją specjalne opcje, ułatwiające konfiguracje konkretnego typu projektu np. projektu używającego QT. Jest ich bardzo dużo, nie będę ich tutaj przytaczał.

Dodanie zależności

Załóżmy, że budujemy bibilitekę, w której potrzebujemy , której nie mamy w ogóle w naszym systemie. Dzięki  wystarczy zmodyfikować nasz  i wszystkie zależności zostaną automatycznie pobrane:
Oczywiście po zawołaniu komendy budującej zostaniemy zapytani czy pobrać zależności. Jeśli z góry wiemy, że chcemy zainstalować wszystko można się pokusić o użycie flagi "zawsze na tak":

Powyżej podawaliśmy zależności jako obowiązkowe, możemy ich użyć w sposób opcjonalny:


Możemy też sprecyzować wersje pakietu, a nawet alias na nazwę pakietu:

Dużym udogodnieniem jest, że można wszystkie zależności podać w jednej komendzie np.:

Instalowanie zależności przy użyciu wskazanych managerów pakietów typu vcpkg/conan/bref

Jest to możliwe, wystarczy poprzedzić nazwę zależności odpowiednią nazwą managera pakietów np.:


Oczywiście te zależności należy dodać do projektu, przykładowy plik  z dokumentacji:

Zależności te widać na obrazku ze strony dokumentacji xmake:

Instalowanie pakietów przy użyciu xmake

Pożądane pakiety możemy również zainstalować komendą, np.:

Alternatywnie możemy podać wersję:
Ponadto mamy możliwość wybrania odpowiedniej wersji biblioteki (debug, shared):
Wreszcie mamy możliwość sprecyzowania konfiguracji pod pakiet:
Nie zapomnijmy też, że mamy możliwość wskazania konkretnego managera pakietów (który musi być zainstalowany w systemie):

Olbrzymią zaletą instalacji zależności przy pomocy xrepo jest możliwość wyświetlenia flag linkowania/kompilacji:
Jeśli potrzebujemy tylko jedno z tych możemy odpytać bezpośrednio:

Możliwe źródła zależności

Jest ich bardzo wiele, nawet te wbudowane w daną dystrybucję linuxa:

• Oficjalne repozytorium xmake-repo
• Oficjalny manager pakietów
  Xrepo
• Manager pakietów Conan (przykład zależności:
  conan::openssl/1.1.1g
  )
• Manager pakietów Conda (przykład zależności:
  conda::libpng 1.3.67
  )
• Manager pakietów Vcpkg (przykład zależności:
  vcpkg:ffmpeg
  )
• Manager pakietów Homebrew/Linuxbrew (przykład zależności:
  brew::pcre2/libpcre2-8
  )
• Pacman dla dystrybucji archlinux/msys2 (przykład zależności:
  pacman::libcurl)
• Apt dla dystrybucji ubuntu/debian (przykład zależności:
  apt::zlib1g-dev
  )
• Manager pakietów języka C Clib (przykład zależności:
  clib::clibs/bytes@0.0.4
  )
• Manager pakietów języka D https://code.dlang.org/ (przykład zależności:
  dub::log 0.4.3)
• Portage dla dystrybucji Gentoo/Linux (przykład zależności:
  portage::libhandy
  )
• Manager pakietów języka programowania nimlang Nimble (przykład zależności:
  nimble::zip >1.3
  )
• Repozytoria użytkownika na github.com

Usuwanie pakietu

Informacje o zainstalowanym pakiecie

Listowanie aktualnie zainstalowanych pakietów

Dodanie pakietu z repozytorium github

Jest możliwe zarówno prywatne jak i publiczne repozytorium (szczegóły):

Można też w pliku  dodać własne repozytoria:

Możliwość wysłania własnego pakietu do oficjalnego repozytoium

Często managery pakietów nie mają wszystkiego, na szczęście każdy może zgłosić własny pakiet. Wymaga to kilka kroków, ale jest szczegółowo opisane w oficjalnym tutorialu.

Pakiety lokalne

Czasami zależności znajdują się w repozytorium projektu, mogą to być zależności xmake'a, które są włączane w specjalny sposób (np. są w repozytorium). Szczegóły w dokumentacji.

Używanie funkcji CMake'a z wnętrza xmake'a

Twórcy xmake zdają sobie sprawę, że CMake stanowi pewien standard, dlatego udostępniają wiele funkcjonalności korzystających z tego standardu.

Możliwość znalezienia pakietu zainstalowanego w systemie przy użyciu CMake'a

Dodawanie zależności korzystających z CMake'a

Wskazywanie komponentów:


Domyślne przełączyniki pakietów:

Zmienne środowiskowe:

Możliwość używania pakietów z xmake'a w CMake'u

Sprowadza się do tego, że instalujemy odpowiedni pakiet do CMake'a, przy pomocy którego ładujemy zależności do pliku CMake. Jest to opisane w oficjalnym tutorialu.

Inne możliwości xmake'a

Tryb cichy logowania

Tryb wylewny logowania (ang. verbose)

Środowisko izolowane

W temacie zależności - możliwe jest utworzenie wirtualnego środowiska izolowanego dla zależności (jak python venv): .
Aby wyjść ze środowiska izolowanego: .

Generowanie konkurencyjnych plików konfigracyjnych dla projektów

Xmake wspiera również generowanie m.in. CMake, Ninja, komendy kompilacji, VisualStudio z projektu używającego xmake'u:

• xmake project -k makefile
• xmake project -k cmakelists
• xmake project -k ninja
• xmake project -k compiler_flags
• xmake project -k xcode
• xmake project -k vsxmake -m "debug;release"
   alternatywnie można podać wersję:
  
  xmake project -k [vsxmake2010|vsxmake2013|vsxmake2015|..] -m "debug;release"

Integracja z IDE

Narzędzie  posiada wtyczki dla popularnych środowisk programistycznych:

• VS Code
• Sublime
• Idea
• nvim
• vim
• visualstudio
• qtcreator

Wykrywanie ustawień systemu i architektury

Zaletą CMake'a jest możliwość sprawdzenia nie tylko zależności, ale również m.in. typów, nagłówków, czy funkcjonalności kompilatora itp.  również ma taką możliwość, po włączeniu odpowiedniego modułu np.
Więcej informacji na stronie dokumentacji.

Rodzaje targetów

Czyli to co ustawiamy przez komendę  (więcej szczegółów):

• binary
   - program binarny (wykonywalny)
• static
  - biblioteka statyczna
• shared
  - biblioteka dynamiczna
• object
  - skompilowana kolekcja obiektów
• headeronly
  - kolekcja nagłówków
• phony
  - jest to pusty target, służy do wskazania zależności między targetami

Zdalne, rozproszone budowanie, unity building

Narzędzie jest wyposażone też w funkcje: zdalnnego budowania, rozproszonego budowania, unity building.

Generowanie dokumentacji doxygen

W tym celu wystarczy zawołać:

Różne style graficzne

Ciekawostką jest możliwość zmiany szablonów działania w konsoli narzędzia :

Pozostałe ustawienia

Jest też bardzo dużo innych, mniej popularnych ustawień np. tworzenie własnych reguł dla plików o określonych rozszerzeniach, ustawienie zestawów narzędzi (ang. toolchain), ustawienia pakietów i zależności między nimi. Poza tym również jest możliwe pobieranie informacji o pakietach, targetach, opcjach, modułach wbudowanych i rozszerzeniach modułów.

Płatne wsparcie

Narzędzie xmake jest bezpłatne, natomiast można skorzystać z płatnego wsparcia.

API ściąga (ang. cheetsheet)

Czyli nazwy niewymienione wcześniej, które mogą się przydać.

Wbudowane predykaty

Czyli funkcje zwracające prawdę lub fałsz, na których podstawie można dokonać ustawień warunkowych, przykładowo:

funkcja	opis	przykłady
is_os	czy aktualnym systemem jest ten podany w argumencie (można podać wiele systemów)	windows, linux, android, macosx, ios
is_arch	czy aktualna architektura jest jedną z tych podanych w argumencie	x86_64, i386
is_plat	czy aktualnie mamy podaną platformę	windows, linux, macosx, android, iphoneos, watchos
is_host	czy kompilacja odbywa się na danym systemie	windows, linux, macosx
is_subhost	czy budujemy na podsystemie	msys, cygwin
is_subarch	czy budujemy na podarchitekturę (dotyczy to msys i cygwin)
is_mode	czy jest to podany tryb kompilacji	debug, release, profile
is_kind	czy jest używany podany tryb targetu	static, shared
is_config	czy ustawiono daną opcje konfiguracyjną. Przykładowo opcję test  ustawiamy tak: xmake f --test=hello1
has_config	jw. z tymże wprowadzona w wersji 2.2 xmake'a
has_package	czy dany pakiet jest dostępny	tbox

Funkcje ustawiające projekt

Poniżej jest opis wybranych funkcji globalnych ustawiających projekt (całość w dokumentacji):

set_project("...")	ustawienie nazwy projektu
set_version("1.0.1")	ustawienie wersji projektu, możliwe argumenty opcjonalne: {build = "%Y%m%d%H%M", soname}
set_xmakever("2.1.0")	ustawienie minimalnej wersji xmake
add_moduledirs("$(projectdir)/modules")	dodanie ścieżki z własnymi modułami
if get_config("myconfig") == "xxx" then     add_defines("HELLO") end	pobranie konfiguracji
set_config("name", "value")	ustawienie domyślnej konfiguracji, którą można zmienić przy użyciu komendy: xmake f --name=value

Dodatkowe ustawienia targetu

Robimy to pod targetem, czyli:
Poniżej wymieniłem wybrane ustawienia (pełna lista znajduje się w dokumentacji, ustawień tych jest bardzo dużo):

set_strip("...")	przycinanie dymboli debugowych np. set_strip("all")
set_default(true)	domyślny target (czyli budowany gdy nie sprecyzujemy inaczej)
set_basename("xxx_$(mode)_$(arch)")	ustawienie domyślnej nazwy pliku wynikowego, do niej zostaną dodane rozszerzenia czy prefixy
set_filename("")	ustawia nazwę, do której nie są dodawane prefixy ani suffixy (rozszerzenia)
set_extension("exe")	ustawienie rozszerzenia
set_warnings("...")	ustawia różne poziomy warningów, np. set_warnings("all", "error") odpowiada -Wall -Wextra -Weffc++ / -Weverything  i -Werror  (wszystkie możliwości)
set_optimize()	optymalizacja kompilatora np. set_optimize("fastest") , (wszystkie możliwości)
set_languages("cxx20", "c17")	ustawienie standardu kompilatora dla różnych języków, w tym wypadku C++20 i C17
set_targetdir("/tmp/build")	ustawienie katalog wynikowy zbudowanego targetu
add_rules()	możliwość utworzenia reguły obsługi plików o danym rozszerzeniu np. dla nieobsługiwanych języków programowania (więcej informacji)
on_clean(...)	ustawienie funkcji wołanej podczas czyszczenia np. target("test")     on_clean(function (target)         os.rm(target:targetfile())     end)
set_pcxxheader("header.h")	ustawienie nagłówka jako prekompilowany
remove_files("src/test.c")	możliwość usunięcia pliku z plików z których powstaje target (przydatne gdy używamy np. add_files("src/*.c") )
add_rpathdirs()	ustawienie ścieżki RPath
add_cflags	dodanie dodatkowych flag kompilatora C
add_cxflags	dodanie dodatkowych flag kompilatorów C i C++
add_cxxflags	dodanie dodatkowych flag kompilatora C++
add_ldflags	dodanie flag linkera
set_toolset("cc", "$(projectdir)/tools/bin/clang-5.0")	ustawienie zestawu narzędzi, co może być przydatne gdy w projekcie zawieramy np. własny kompilator
set_rundir("$(projectdir)/xxx")	ustawienie ścieżki wykonywania programu
add_runenvs("PATH", "/tmp/bin", "xxx/bin")	ustawienie zmiennych środowiskowych wykonywanego programu
set_encodings("utf-8")	ustawienie kodowania plików źródłowych i docelowych (możliwe jest tylko źródłowych lub tylko docelowych)
add_forceincludes("config.h")	dodanie nagłówka podczas kompilacji bez ręcznego dodawania go w kodzie
add_extrafiles("assets/other.txt")	dodanie pliku, który nie jest kodem, do projektu
add_tests(...)	umożliwia dodanie testów, użycie tej komendy jest bardziej skomplikowane, dlatego odsyłam do dokumentacji

Dla ułatwienia kolejność wywołania funkcji przy budowaniu targetu:
 ->  ->  ->  ->  ->  ->
Mamy też:  ->  ->

Wbudowane zmienne

$(os)	aktualny system operacyjny
$(host)	natywny system operacyjny
$(tmpdir)	katalog tymczasowy
$(curdir)	aktualna ścieżka
$(buildir)	katalog do budowania
$(scriptdir)	katalog aktualnego skryptu, gdzie jest plik xmake.lua
$(globaldir)	katalog z globalnymi ustawieniami, domyślnie dla linuxa jest to ~/.config
$(configdir)	katalog konfiguracyjny projektu
$(programdir)	katalog instalacyjny skryptów xmake'a
$(projectdir)	katalog główny projektu (ang. root directory)
$(shell)	wykonywalna komenda powłoki np. target("test")     set_kind("binary")     if is_plat("linux") then         add_ldflags("$(shell pkg-config --libs sqlite3)")     end
$(env)	zmienne środowiskowe
$(reg)	wartość konfiguracyjna rejestru windows

Poza zmiennymi wbudowanymi można w łatwy sposób tworzyć własne:

taką zmienną odczytujemy w następujący sposób:

Bibliografia

• Strona domowa xmake
• Strona TBox.org, na której opisują zmiany w kolejnych wydaniach xmake, robią to bardzo obszernie
• Strona domowa XRepo
• Wideo tutoriale na temat xmake'a
• Przykładowe xmake'i wraz z opisem na stronie dokumentacji
• Tutorial dla XRepo

Autorzy artykułu

Autor	Zakres zmian	Afiliacja
Bazior Grzegorz	Utworzenie artykułu	Pracownik AGH w Krakowie