From bbd58b3d43aaef48f1ffd3b1bd8278aaf65ec145 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20Ho=CC=88rler?= Date: Thu, 5 Jul 2018 08:10:31 +0200 Subject: [PATCH] update doc --- docs/build-tutorial-Unix-MacOS-HighSierra.md | 100 ++++++++++ ...torial.md => build-tutorial-linux-arch.md} | 0 docs/build-tutorial-linux-debian.md | 188 ++++++++++++++++++ docs/faq.md | 24 +++ docs/target-devices-and-platforms.md | 4 +- 5 files changed, 314 insertions(+), 2 deletions(-) create mode 100644 docs/build-tutorial-Unix-MacOS-HighSierra.md rename docs/{build-tutorial.md => build-tutorial-linux-arch.md} (100%) create mode 100644 docs/build-tutorial-linux-debian.md create mode 100644 docs/faq.md diff --git a/docs/build-tutorial-Unix-MacOS-HighSierra.md b/docs/build-tutorial-Unix-MacOS-HighSierra.md new file mode 100644 index 0000000..f684a12 --- /dev/null +++ b/docs/build-tutorial-Unix-MacOS-HighSierra.md @@ -0,0 +1,100 @@ +# Tutorial to build Servonk on MacOS High Sierra + +This tutorial was made for MacOS, an Unix based distro, but can be expanded to other distros. +Keep in mind there are different ways to use this technology. +1. mobile +2. desktop + +The technology stack is depending on different blocks as the hardware is never the same. + +1. Servonk Stack for mobile: +- Hardware +- B2G +- servonk +- Servo +- HTML Frontend + +2. Servonk Stack for desktop: +- Hardware +- servonk +- Servo +- HTML Frontend + +thats why you can leave out the B2G Layer when building for desktop. + +## General Dependencies + +Your Machnine will need at least 8Gb of RAM and 5Gb of Harddisk space +to build for desktop and 80Gb to build for a mobile successfully. + +Here we use Homebrew allthroug its possible to use any Package Manager +distributing the same packages. + +Install Homebrew +```sh +/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" +``` +Install dependencies +```sh +brew install automake pkg-config python@2 cmake yasm +``` +Install Rustup the dependency manager of Rustup +```sh +curl https://sh.rustup.rs -sSf | sh && \ +export PATH="$HOME/.cargo/env:$PATH" && \ +source $HOME/.cargo/env +``` +Download servonk to the directory {YOUR_USER}/Servonk or change it to what you like... +```sh +git clone https://github.com/fabricedesre/servonk.git && \ +cd ~/servonk/ +``` +Install the toolchain +```sh +./bootstrap.sh +``` + +## B2G steps + +FirefoxOS was built on the older HTML Renderer Gecko. It's +early development name was Boot to Gecko (B2G). +As technology changes the HTML Renderer of Firefox changed and Gecko was +succeded by Servo. Therefore this Project aims to change the +Hardwareabstractionlayer (HAL) which was caled Gonk and its toolchain to +boot a mobile in to the new HTML Renderer Servo what also gives this project +the name servonk. You need to do a B2G build for your device +(eng or userdebug to get root access), as this is not properly setup with +the Android build system yet. If you need more info, [this is a good first place to start](https://developer.mozilla.org/en-US/docs/Archive/B2G_OS/B2G_OS_build_prerequisites). + +For MacOS and OSX its realy hard to build B2G as it depends on a case-sensitive +System. If you feel educated enough you can try to install MacOS on a +case-sensitive Partitition. Described here: [TODO] + +## Servonk steps + +To build, run: + +```sh +# For a Gonk build +./servonk build gonk --release + +# Or for a desktop version +./servonk build glutin --release +``` + +## Running + +On desktop run: + +```sh +./servonk run glutin +``` + +On mobile/Gonk, you first need to flash your device with B2G before running: + +```sh +./servonk flash gonk +./servonk run gonk +``` + +The lockscreen code is 4242. diff --git a/docs/build-tutorial.md b/docs/build-tutorial-linux-arch.md similarity index 100% rename from docs/build-tutorial.md rename to docs/build-tutorial-linux-arch.md diff --git a/docs/build-tutorial-linux-debian.md b/docs/build-tutorial-linux-debian.md new file mode 100644 index 0000000..a4b1f50 --- /dev/null +++ b/docs/build-tutorial-linux-debian.md @@ -0,0 +1,188 @@ +# Tutorial to build Servonk on Debian distros + +This tutorial was made for Ubuntu, an Debian based distro, but can be expanded to other distros. +Keep in mind there are different ways to use this technology. +1. mobile +2. desktop + +The technology stack is depending on different blocks as the hardware is never the same. + +1. Servonk Stack for mobile: +- Hardware +- B2G +- servonk +- Servo +- HTML Frontend + +2. Servonk Stack for desktop: +- Hardware +- servonk +- Servo +- HTML Frontend + +thats why you can leave out the B2G Layer when building for desktop. + +## General Dependencies + +Your Machnine will need at least 8Gb of RAM and 5Gb of Harddisk space +to build for desktop and 80Gb to build for a mobile successfully. + +```sh +sudo apt -y update && sudo apt -y upgrade && sudo apt -y update && \ + sudo apt -y install git curl wget autoconf libx11-dev \ + libfreetype6-dev libgl1-mesa-dri libglib2.0-dev xorg-dev \ + gperf g++ build-essential cmake virtualenv python-pip \ + libssl1.0-dev libbz2-dev libosmesa6-dev libxmu6 libxmu-dev \ + libglu1-mesa-dev libgles2-mesa-dev libegl1-mesa-dev libdbus-1-dev \ + libharfbuzz-dev ccache clang llvm-dev libclang-dev +``` +Install Rustup the dependency manager of Rustup +```sh +curl https://sh.rustup.rs -sSf | sh && \ +export PATH="$HOME/.cargo/env:$PATH" && \ +source $HOME/.cargo/env +``` +Download servonk to the directory {YOUR_USER}/Servonk or change it to what you like... +```sh +git clone https://github.com/fabricedesre/servonk.git && \ +cd ~/servonk/ +``` +Install the toolchain +```sh +./bootstrap.sh +``` + +## B2G steps (unverified! please file a Pullrequest (PR) if it works or open an issue) + +In earlyer days FirefoxOS was built on the older HTML Renderer Gecko. It's +early development name was Boot to Gecko (B2G). +As technology changes the HTML Renderer of Firefox changed and Gecko was +succeded by Servo. Therefore this Project aims to change the +Hardwareabstractionlayer (HAL) which was caled Gonk and its toolchain to +boot a mobile in to the new HTML Renderer Servo what also gives this project +the name servonk. You need to do a B2G build for your device +(eng or userdebug to get root access), as this is not properly setup with +the Android build system yet. If you need more info, [this is a good first place to start](https://developer.mozilla.org/en-US/docs/Archive/B2G_OS/B2G_OS_build_prerequisites). + +Clone the B2G repository and enter to b2g directory. + +```sh +git clone https://github.com/mozilla-b2g/B2G && cd b2g +``` + +Configure USB access. + +```sh +wget -S -O - https://raw.githubusercontent.com/cm-b2g/B2G/1230463/tools/51-android.rules | sudo tee >/dev/null /etc/udev/rules.d/51-android.rules; sudo udevadm control --reload-rules +``` + +Configure ccache + +```sh +ccache -M 50G +``` + +install B2G dependencies + +```sh +sudo apt install -y alsa-lib autoconf2.13 bison firefox flex + gcc-multilib libnotify libxt libx11 mesa multilib-devel + wireless_tools yasm zip lib32-mesa lib32-mesa-libgl lib32-ncurses + lib32-readline lib32-zlib lzop +``` + +Configure Python. Remember to use virtualenv every time you try to compile. + +```sh +sudo apt install python-virtualenvwrapper +source /usr/bin/virtualenvwrapper.sh +mkvirtualenv -p `which python2` firefoxos +workon firefoxos +``` + +Verify that all works. + +```sh +python --version +``` + +Gives as result `Python 2.7.XX`. + +Install Android tools. + +```sh +sudo apt install android-sdk +``` + +Optionally you can install all the Android development tools. + +```sh +sudo apt install android-sdk android-sdk-build-tools android-sdk-platform-tools android-platform +``` + +Plug your phone and make a copy of propietary blobs. Ensure you device has [Remote Debugging](https://developer.mozilla.org/en-US/docs/Archive/B2G_OS/Debugging/Developer_settings#Remote_debugging) enabled in [Developer settings](https://developer.mozilla.org/en-US/docs/Archive/B2G_OS/Debugging/Developer_settings). Confirm your device is visible with the `adb devices` command, you should see something similar to this: + +```sh +$ adb devices +List of devices attached +ABCXXXXXXX device +``` + +If no device is listed, check your UDEV rules. + +If you have permission issues, check that your screen is unlocked and that you have authorized access to your phone. You see a message on your device for that. If the issue persists used `adb root` and `adb remount`. + +Back up the phone's partitions with the adb pull command: + +```sh +adb pull /system /system +``` + +Depending on the phone, you may also need to pull the /data and /vendor directories: + +```sh +adb pull /data /data +adb pull /vendor /vendor +``` + +If the pull commands fail with an _insufficient permission_ message, try the following: + +- Check you have granted root permissions within your custom ROM (e.g. under CyanogenMod, change Settings > System > Developer Options > Root Access to Apps and ADB or ADB only). +- Verify that you have set up the udev rule correctly (see For Linux: configure the udev rule for your phone). + +Remember to plug your phone. Now config, build and flash B2G on your phone. This is only necessary to build gonk, not gecko or gaia. A simple way to remove these from the build after running ./config.sh is to edit b2g.mk in gonk-misc repository and comment out the gecko and gaia lines, as shown in this git diff: https://pastebin.com/sdQG3Tki + +```sh +./config.sh +./build.sh +./flash.sh +``` + +## Servonk steps + +To build, run: + +```sh +# For a Gonk build +./servonk build gonk --release + +# Or for a desktop version +./servonk build glutin --release +``` + +## Running + +On desktop run: + +```sh +./servonk run glutin +``` + +On mobile/Gonk, you first need to flash your device with B2G before running: + +```sh +./servonk flash gonk +./servonk run gonk +``` + +The lockscreen code is 4242. diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..d43087d --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,24 @@ +# Freeuently asked Questions (ordered in A-Z) + +## Servonk Stack + +- Hardware +- B2G (HAL for mobile) +- servonk +- Servo +- HTML Frontend + +## Build failing + +### don't know why +Most of the times the user is trying to build on a system with less than 8Gb +of RAM. Check in console with the testline below. + +Linux | output has to be >8'000'000 as its in kB +```sh +grep MemTotal /proc/meminfo | awk '{print $2}' +``` +MacOS | output has to be >8'000'000'000 as its in Byte +```sh +sysctl -a | grep hw.memsize +``` diff --git a/docs/target-devices-and-platforms.md b/docs/target-devices-and-platforms.md index b3a456a..33fad50 100644 --- a/docs/target-devices-and-platforms.md +++ b/docs/target-devices-and-platforms.md @@ -1,5 +1,5 @@ # Currently working devices: -Currently Servonk is targetting Gonk from B2G derived from Android Lollipop. There's also the desktop build with Glutin. +Currently Servonk is targetting Gonk from B2G derived from Android Lollipop. There's also the desktop build with Glutin. Using Gonk-L: * Sony Xperia Z3 Compact @@ -11,7 +11,7 @@ Using Glutin: To do: add links to the build instructions for each of the working devices. # Work in progress -* macOS using Glutin - @novski in Telegram, confirmed built, instructions to be written and need confirmation it's running. +* macOS using Glutin - build confirmed, not runing. * Flame - @penserbjorne has stated a desire to get this working in the repo issues. # Potential targets