Changes between Version 31 and Version 32 of UsersGuide/CompilingFromSource

Timestamp:

2019-08-19T11:43:48Z (5 years ago)

Author:

Jiří Zárevúcky

Comment:

—

UsersGuide/CompilingFromSource

@@ -18 +18 @@
 
 {{{
-$ git clone git@github.com:HelenOS/helenos.git HelenOS
-}}}
-
-If you do not have !GitHub account (with public keys set), you may need to use HTTPS instead:
-
-{{{
 $ git clone https://github.com/HelenOS/helenos.git HelenOS
 }}}
 
-''Note:'' To get versions up to 0.7.1 you have to access the abandoned Bazaar repository
-
-{{{
-$ bzr branch bzr://bzr.helenos.org/mainline HelenOS
-}}}
-
-''Note:'' To get versions older than 0.4.1 you have to access the original Subversion repository
-
-{{{
-$ svn checkout svn://svn.helenos.org/HelenOS/trunk HelenOS
-}}}
-
 == 2. Build a supported cross-compiler ==
 
-Use our script to install a supported cross-compiler toolchain. The script either needs to be run as the `root` user (because it will install the cross-compiler to the `/usr/local/cross/ia32` directory) or you need to set the `CROSS_PREFIX` environment variable to use custom toolchain installation directory.
+Use our script to install a supported cross-compiler toolchain. The script either needs to be run as the `root` user (because it will install the cross-compiler to the `/usr/local/cross` directory) or you need to set the `CROSS_PREFIX` environment variable to use custom toolchain installation directory.
 
 {{{
 $ cd HelenOS/tools
-$ ./toolchain.sh ia32
-}}}
-
-'''Note:''' In older revisions of the source tree the ''toolchain.sh'' script was present in the ''contrib'' directory (not the ''tools'' directory where it is now).
+$ ./toolchain.sh amd64
+}}}
 
 The toolchain script will print a list of software packages that are required for the toolchain to correctly build. Make sure you install all the dependencies. Unfortunately, the script cannot install the required dependencies for you automatically since the host environments are very diverse. In case the compilation of the toolchain fails half way through, try to analyze the error message(s), add appropriate missing dependencies and try again.
@@ -55 +35 @@
 
 {{{
-$ sudo apt install build-essential wget texinfo bison dialog python-yaml genisoimage
+$ sudo apt install build-essential wget texinfo flex bison dialog python-yaml genisoimage
 }}}
 
@@ -78 +58 @@
 == 4. Configure and build ==
 
-Go back to the source root of HelenOS and start the build process
-
-{{{
-$ cd ..
-$ make PROFILE=ia32
+Since the summer of 2019, HelenOS uses the Meson build system.
+Make sure you have a recent-enough version of Meson and Ninja.
+The safest bet is installing both using `pip3` tool.
+
+{{{
+$ pip3 install ninja
+$ pip3 install meson
+}}}
+
+Meson does not support in-tree builds, so you have to create a directory
+for your build. You can have as many build directories as you want, each with
+its own configuration. `cd` into your build directory and run `configure.sh`
+script which exists in the source root. `configure.sh` can be run with a profile
+name, to use one of the predefined profiles, or without arguments for interactive
+configuration.
+
+{{{
+$ cd HelenOS
+$ mkdir -p ../HelenOS-build/amd64
+$ cd ../HelenOS-build/amd64
+$ ../../HelenOS/configure.sh amd64
+}}}
+
+Note: If you installed the toolchain to a custom directory, make sure `CROSS_PREFIX`
+environment variable is correctly set.
+
+Once configuration is finished, use `ninja` to build HelenOS.
+Invoking `ninja` without arguments builds all binaries and
+debug files, but not bootable image. This is because during
+development, most builds are incremental and only meant to check
+that code builds properly. In this case, the time-consuming process of
+creating a boot image is not useful and takes most time. This behavior
+might change in the future.
+
+In case you want to rebuild the bootable image, you must invoke
+`ninja image_path`. This also emits the name of the bootable image into the
+file `image_path` in build directory.
+
+{{{
+$ ninja
+$ ninja image_path
 }}}
 
 Now HelenOS should automatically start building.
 
-'''Note:''' If you installed the toolchain to a custom directory, make sure `CROSS_PREFIX` environment variable is correctly set.
 
 == 5. Run it ==
@@ -106 +121 @@
 
 == Advanced Topics ==
+
+=== Building all predefined profiles ===
+
+First, you need to build all required cross-compiler targets.
+The `toolchain.sh` script makes this easy.
+
+Remember to set your `CROSS_PREFIX` variable if you want non-default location.
+
+{{{
+$ cd HelenOS/tools
+$ ./toolchain.sh essential
+}}}
+
+Next, create a directory in which you want build files to be created.
+
+{{{
+$ cd HelenOS
+$ mkdir ../HelenOS-build-all
+$ cd ../HelenOS-build-all
+}}}
+
+To run the build, use `tools/build_all.sh`.
+
+{{{
+$ ../HelenOS/tools/build_all.sh
+}}}
+
+Now wait for all profiles to be configured and built.
+This is the recommended way to check all default (supported) configurations.
+
+If you are lazy, you can run `tools/build_all.sh` right in the source directory.
+
+{{{
+$ cd HelenOS
+$ tools/build_all.sh
+}}}
+
+This will build everything in a `build_all` subdirectory in the source directory, as a special case.
 
 === Which profiles are available? ===
@@ -137 +190 @@
 With manual configuration you can change the initial screen resolution, disable building of some components, etc.
 
-'''Warning:''' Do not select a different compiler unless you really know what you are doing! If you use ''gcc_native'' instead of ''gcc_cross'', it won't work, so please don't ask in the mailing list! Building HelenOS with a native compiler is '''not supported'''!
-
 To configure:
 
 {{{
-$ make distclean && make config
+$ cd HelenOS-build
+$ ../HelenOS/configure.sh   # Interactive configuration
+$ ninja                     # Build code
+$ ninja image_path          # Build boot image
 }}}
 
@@ -148 +202 @@
 
 {{{
-$ make distclean && make
-}}}
-
-this will cause the HelenOS build to automatically start once you are done with the configuration.
+$ cd HelenOS-build
+$ ../HelenOS/configure.sh profile
+$ ninja config              # Interactive configuration
+$ ninja                     # Build code
+$ ninja image_path          # Build boot image
+}}}
+
+You can change configuration at any time, and the build system should be able to resolve all necessary rebuilds automatically.
+Note however that you cannot change target platform/machine type once the initial configuration is finished.
+To build for a different device, you need to create a new build directory for it.
 
 === Building release files ===
@@ -157 +217 @@
 This procedure is used to create HelenOS realease files before releasing a new HelenOS version, or for simulating that process. The resulting system image is based on one of the predefined configuration profiles (as opposed to the current configuration).
 
-Before building release files make sure you have no uncommitted changes. These will not be build since we are building from exported sources.
-
-To build all release files go to the source root and run:
-
-{{{
-$ make release
-}}}
-
-To build an individual release file go to the source root and run:
-
-{{{
-$ make -C release release PROFILES=profile_name
-}}}
-
-This builds a release file (boot image / disk image) based on the specified configuration profile `profile_name`.
+Before building release files make sure you have no uncommitted changes. These would get incorporated into the release.
+
+To build all release files, create a build directory and run:
+
+{{{
+$ path/to/HelenOS/tools/release.sh
+}}}
+