Uživatelské nástroje

Nástroje pro tento web


Toto je starší verze dokumentu!


Kompilace Turris OS ze zdrojových kódů

Systém Turris OS je založený na distribuci OpenWrt, do které jsou zahrnuty různé úpravy a software, který například zajišťuje automatické aktualizace nebo analyzuje síťový provoz. Kompletní zdrojové kódy systému jsou k dispozici v gitovém repositáři a je možno jej zkompilovat do binární podoby a nainstalovat na zařízení.

Turris OS je možné zkompilovat prakticky na libovolném počítači. V produkčním prostředí je systém kompilován automaticky na systému Ubuntu a následující postupy jsou na tomto systému ověřeny. Přesto je možné ho obdobným postupem zkompilovat i na jiných systémech.

V prvním kroce je nutné naklonovat si repositář Turris OS. To je možné provést některým z následujících dvou příkazů (druhý příkaz je pro naklonování z mirroru na serveru GitHub):

git clone https://gitlab.labs.nic.cz/turris/openwrt.git
git clone https://github.com/CZ-NIC/turris-os.git

Příprava vývojového prostředí

Nejlepším způsobem jak zajistit hladký průběh kompilace je použít totožné prostředí jako v produkci. Nejlépe pak nasazením tohoto prostředí do kontejneru, což také umožní oddělení hlavního systému od systému pro kompilaci. Jsou podporovány dvě varianty jak toto učinit, buďto pomocí nástroje Vagrant a nebo pomocí Dockeru.

Vagrant

Vagrant slouží ke snadné správě vývojových prostředí a v repositáři s Turris OS jsou již připraveny skripty, které umožňují toto prostředí vytvořit zadáním několika málo příkazů. Zároveň automaticky zajišťuje synchronizaci mezi hostitelským systémem a vývojovým prostředím, takže je možné v rámci repositáře pracovat se sadou programů, které jsou nainstalovány v hostitelském systému (například s oblíbeným textovým editorem), a změny se okamžitě projeví v jinak izolovaném prostředí, které s hostitelským systémem sdílí pouze složku naklonovaného repositáře a ve kterém spouštíme kompilaci systému.

V prvním kroku je nutné nainstalovat aplikaci Vagrant. To je možné provést pomocí správce balíků (např. APT v Ubuntu/Debian). V repositářích některých distribucí se však nachází zastaralé verze, které pozbývají potřebné funkce a mohou tak způsobovat problémy. V tom případě je doporučeno nainstalovat verzi staženou z oficiálních stránek.

Po instalaci aplikace Vagrant je nutné doinstalovat plugin vagrant-lxc, který umožňuje používat LXC kontejnery. Ty usnadňují oddělení systému pro kompilaci od hlavního systému bez výraznějšího snížení rychlosti kompilace. Tento plugin samozřejmě vyžaduje také instalaci podpory LXC v hlavním systému. Instalaci tohoto pluginu a jeho závislostí by mělo zajistit zadání těchto příkazů (předpokladem je již nainstalovaná aplikace Vagrant):

sudo apt-get install lxc
vagrant plugin install vagrant-lxc

V posledním kroku je potřeba vytvořit symbolický odkaz (nebo zkopírovat) na soubor s definicí vývojového prostředí do kořenového adresáře s naklonovaným repositářem:

ln -s vagrant/Vagrantfile

Nyní je již možné spustit instanci vývojového prostředí, se kterou budete pracovat, to provedete příkazem vagrant up --provider=lxc (příznak --provider=lxc je potřebný pouze při prvotní inicializaci). Tento příkaz se nám bude hodit pokaždé, kdy instanci ukončíme (pomocí vagrant halt nebo po restartu hostitelského systému). Pokud budete z nějakého důvodu potřebovat vývojové prostředí přeinstalovat (ekvivalent přeinstalování celého systému) nebo odstranit, bude se hodit příkaz vagrant destroy.

Pro přístup do systému slouží příkaz vagrant ssh spuštěný v kořenovém adresáři repositáře. Tím se otevře SSH spojení do kontejneru s vývojovým prostředím, se kterým je již možné pracovat jako s normálním systémem. Adresář, který je synchronizován s repositářem v hostitelském systému, je v systému dostupný v cestě /openwrt.

Docker

Docker je oproti nástroji Vagrant více rozšířený a tak je možné že již na vašem systému je nainstalovaný a nastavený. Soubory potřebné k vytvoření Docker kontejnerů se nacházejí v naklonovaném repositáři Turris OS v adresáři 'Docker'. Obsahem jsou dva skripty a to build-all a run a především soubory popisující Docker kontejnery.

Prvním krokem je vytvoření kontejnerů. Skript build-all obsahuje pět řádek volajících docker, které postupně vytvoří pět kontejnerů. Jejich jména a význam je následující:

  • base - Základní systém obsahující všechny závislosti potřebné pro sestavení Turris OS. Do adresáře '/home/build/openwrt' jsou naklonovány zdrojové kódy a to v nejnovější verzi z větvě `test` (větev na které probíhá vývoj).
  • omnia-toolchain - Vyžaduje a vychází z base. Je v něm nastavena konfigurace pro Turris Omnia a obsahuje zkompilovaný toolchain. Balíčky ale nejsou zkompilovány. Toto se může hodit pokud je nutné nestavit pouze jeden balíček, nikoli celý systém.
  • omnia - Vyžaduje a vychází z omnia-toolchain. V tomto kontejneru je sestaven základní systém, systém pro Turris Omnia a kompilace při malé změně by tak měla být rychlá. Ale ani v tomto kontejneru nejsou zkompilovány všechny balíčku (to by vyžadovalo velké množství času).
  • turris-toolchain - Vyžaduje a vychází z base. Je v něm nastavena konfigurace pro Turris 1.x a je v něm zkompilovaný toolchain. Balíčky ale nejsou zkompilovány. Toto se může hodit pokud je nutné sestavit pouze jeden balíček, nikoli celý systém.
  • turris - Vyžaduje a vychází z turris-toolchain. V tomto kontejneru je sestaven základní systém pro Turris 1.x a kompilace při malé změně by tak měla být rychlá. Ale ani v tomto případě nejsou zkompilovány všechny balíčky (to by vyžadovalo velké množství času).

Pokud chcete ušetřit čas a místo tak můžete odstranit řádky pro vámi necílenou platformu. Následně spusťte skript build-all. Tento proces může trvat i hodiny, záleží na výkonu hardwaru na kterém kompilace běží a na tom které kontejnery vytváříte.

Poté co jsou kontejnery vytvořeny, tak je do nich možné přistoupit pomocí skriptu run. Tento skript jako první argument očekává volitelně jméno kontejneru (tedy např. ./run omnia). Pokud není žádný argument předán, tak se pokusí připojit do kontejneru omnia-toolchain.

Pozor, v případě Dockeru, po ukončení kontejneru jsou všechny změny zahozeny, pokud nenastavíte jinak. Také na rozdíl od nástroje Vagrant nepracuje Docker s originálním vámi naklonovaným repositářem.

V následujících sekcích rozlišujte který kontejner jste se rozhodli použít. V případě base musíte provést celý postup jak je popsán. V případě ostatních Docker kontejnerů není nutné dělat update feedů a nastavení konfigurace, můžete se rovnou přesunout na kompilaci. V takovém případě také není doporučeno používat compile_fw skript, protože jako první krok provádí čištění repositáře.

Nastavení prostředí bez kontejnerů

Pokud na vašem systému nemůžete nebo nechcete používat prostředí Vagrant či Docker, je možné nainstalovat závislosti kompilace systému přímo do hostitelského systému. Tyto závislosti lze nalézt v inicializačním skriptu vagrant/vagrant_bootstrap.sh, který se spouští po prvním spuštění prostředí Vagrant. V systémech založených na distribuci Debian bude možné pravděpodobně příkazy v něm použité použít beze změny, v jiných systémech bude nutné nalézt a nainstalovat software, který instalovaným balíčkům odpovídá. V hledání může pomoct tabulka na wiki OpenWrt. Uvedený skript zároveň upravuje URL pro stahování balíčků a volitelně též umožňuje instalaci doplňování argumentů pro příkaz make v buildrootu pomocí rozšíření openwrt-bash-completion.

Poslední možností je použít pro kompilaci plně virtualizovaný systém. Tato metoda je nejnáročnější na prostředky (CPU a operační paměť), ale je možné ji použít na nejširším množství systémů, včetně OS Windows. Pro virtualizaci lze použít například volně dostupnou aplikaci VirtualBox. V tomto případě je vhodné jako instalovaný systém zvolit distribuci Ubuntu - v tom případě stačí po instalaci systému naklonovat repozitář Turris OS a spustit výše uvedený inicializační skript, který se postará o vše ostatní.

Vlastní kompilace Turris OS

Turris OS, respektive OpenWRT, se skládá z velkého množství skriptů. K sestavení Je nutné vykonat několik kroků jako například vytvoření konfigurace, stažení feedů (zdrojů balíčků nad rámec OpenWRT), záplatování feedů a další. Protože dohromady se jedná o komplexní postup tak v Turris OS je implementován compile_fw skript. Ten automatizuje všechny kroky potřebné pro sestavení Turris OS.

V závislosti na cílovém routeru by měl být použit skript compile_omnia_fw (pro Turris Omnia) nebo compile_turris_fw (pro Turris 1.x).

compile_fw skriptu je možné dát argumenty, které jsou následně použity pro volání make pro OpenWRT build. Doporučeným argumentem je -j$(nproc) tak aby sestavení probíhalo paralelně.

Ve výchozím stavu je sestavena pouze minimální sada balíčků. Nejedná se tak o kompletní Turris OS, ale je to dostatečný základ pro například vytváření nových balíčků. Tento typ sestavení se používá pro vývoj a zrychlené sestavování. V závislosti na hardwaru může trvat půl a celou hodinu.

Pro sestavení a nebo vygenerování medkitu je nutné specifikovat proměnnou BUILD_ALL=y v proměnném prostředí při spuštění jednoho z compile_fw skriptů. To je možné udělat takto: BUILD_ALL=y ./compile_omnia_fw (v případě Turris 1.x pak compile_turris_fw). Tento typ sestavení je nutný pro vygenerování vlastního medkitu (archivu s kořenovým souborovým systémem který je možné nahrát do routeru). Tento typ sestavení může trvat více než osm hodin a to v závislosti na použitém hardwaru. Je také náchylný na selhání (způsobené souběhem balíčků).

Pokud narazíte na problém při sestavování tak můžete zkusit snížit hodnotu argumentu -j nebo ji nastavit na -j1 pro vypnutí paralelního sestavování. Tyto problémy jsou způsobené souběhem balíčků při sestavování a obtížně objevitelnými chybějícími závislostmi.

Řešení problémů

Nedostatek místa při vytváření Docker kontejneru

Docker kontejnery zabírají řádově desítky gigabajtů. Pokud jejich vytváření selhalo s hláškou o nedostatku místa, tak v prvním kroku je třeba zkontrolovat zdali vám skutečně nedošlo místo a případně ho uvolnit. Pokud, ale místa máte dostatek, pak je nutné upravit konfiguraci Docker daemonu a to pomocí těchto voleb --storage-opt dm.basesize=40G --storage-opt dm.loopmetadatasize=10G. Výsledná spouštěcí řádka by tak měla vypadat například takto:

dockerd -H fd:// --storage-opt dm.basesize=40G --storage-opt dm.loopmetadatasize=10G

Po této úpravě je nutné Docker daemon restartovat a odstranit všechny doposud vygenerované soubory tak aby se změna aplikovala. Přesná cesta souborů je dána vaším systémem, ale obecně se užívá /var/lib/docker.