Difference between revisions of "Building ReactOS"

From ReactOS Wiki
Jump to: navigation, search
m (replace "suppport" with "support")
m (3. Do the "configure" step)
 
(30 intermediate revisions by 21 users not shown)
Line 1: Line 1:
<!-- '''NOTE: This page is deprecated and is purely here for archival purposes. For instructions on building ReactOS, please see the [http://www.reactos.org/development/build-environment build environment] page of the development guide.''' -->
+
This page describes the steps necessary to build ReactOS.<br>
This page describes the steps necessary to build ReactOS.
+
ReactOS supports building on different operating systems and with different compilers.
 +
Currently GCC, MSVC and LLVM/Clang can be used.
  
== Getting all you need ==
+
The build process differs depending your operating system and the compiler of choice.<br>
=== Setting up a Build Environment ===
+
Each build step in the tutorial is separated by OS/compiler when necessary. Choose ones which fit your configuration.
For building ReactOS you also need the official [[ReactOS Build Environment]]. Please download and install it from that page.
 
  
Make sure that no interfering build environment (such as MSYS) is in your PATH environment variable when building.
+
== Which compiler to use ==
 +
* GCC is currently a recommended option as the most simple to use.
 +
* MSVC compiler can be used for better debugging capabilities (only MSVC builds support windbg debugger).
 +
* Clang support is currently experimental and not advised unless you know what are you doing.
  
<!-- {{Notice|Due to a current bug, the build environment can not use a build folder that contains spaces in its path name.<br />
+
== Prerequisites ==
Under Windows XP and 2003 you  must change the default location of "C:\Documents and Settings\[username]\reactos\".}} -->
+
* A PC with at least 2GB of RAM (4GB preferred), 15GB of free space.
=== Optional: Setup Visual Studio ===
+
* Git version control system.
If you want to use Visual Studio to compile reactos, you need to get one of the supported version, which is VS2010 and later. You can download the free Community Edition of Visual Studio 2015. To compile with VS, open the appropriate VS command prompt and follow the same instructions as for building with the GCC based ReactOS build environment. Note that you still need the ReactOS build environment, which contains CMake and some additional tools, or you can install the latest version of Cmake yourself, but that is not recommended. If you experience problems with the configure stage, e.g. the compiler is reported to not be working, please check if you have installed any additional Windows SDKs or WDK and try again after removing them.
+
* [[ReactOS Build Environment]] (RosBE). Please, always use the latest version available.
 +
* (optional) [https://visualstudio.microsoft.com/downloads/ Microsoft Visual Studio] 2015 or later (or Build Tools for Visual Studio).
 +
* (optional) [https://releases.llvm.org/ LLVM toolchain] 12.0.0 or later.
 +
 
 +
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
 +
<div style="font-weight:bold;line-height:1.6;">Visual Studio installation remarks</div>
 +
<div class="mw-collapsible-content">
 +
* Download the Visual studio 2017 community edition (or later).
 +
: ''When selecting the options, be sure to at least include '''Desktop development with C++'''.''
 +
[[File:Desktop development.png|Desktop development]]
 +
* Ensure you have started visual studio at least once, and you are able to create a working c++ project.
 +
: ''To validate this, choose '''Create a new project''', choose '''Console App''', and use all default options.''
 +
* While installing [[RosBE]], you may choose the option '''Add BIN folder to PATH variable''' (may be added later manually).
 +
[[File:RosBE BIN folder.png]]
 +
</div></div>
 +
 
 +
{{Notice|It is recommended to disable antivirus software before proceeding (or adding a build folder to exceptions), because some AVs may detect ReactOS' system files (in particular, crtdll.dll or csrss.exe) as being infected.}}
  
=== Getting a Working Copy ===
+
== TL;DR ==
The first step in building ReactOS is getting a copy of the source code.
+
<syntaxhighlight lang="dos">
 +
<inside RosBE command prompt>
 +
git clone https://github.com/reactos/reactos
 +
cd reactos
 +
configure.cmd
 +
cd output-MinGW-i386
 +
ninja bootcd livecd
 +
</syntaxhighlight>
  
You can use the exported release source code, but since you are reading this, you are probably interested in keeping up to date with the latest changes, so you will want a "working copy" of ReactOS.
+
== Building instructions ==
To get a working copy of ReactOS, please read the [[Subversion]] page.
+
=== 1. Prepare a command prompt ===
 +
==== Windows/GCC or ReactOS/GCC ====
 +
* Just use the RosBE command prompt (from the Start menu)
  
If you do not use a separate SVN client, the command
+
==== *nix/GCC ====
ssvn create
+
* Invoke <code>RosBE.sh</code> script
from within the build environment will download it.
 
  
== Prerequisites ==
+
==== *nix/Clang ====
{{Notice|You should temporarily disable your antivirus before proceeding, because some of them detect ReactOS's as infected system files.}}
+
* Invoke <code>RosBE.sh</code> script, ensure <code>clang</code> is available in <code>$PATH</code>
  
Before building either the tools or ReactOS itself the output location must be created and prepared. This is an easy step and involves only one command. This command is located in the root of recent revisions of the source code and can be run either from the root directory itself or any other directory you want the build your sources in. Please make sure you are running it from within ReactOS BE:
+
==== Windows/MSVC ====
 +
* Open a Visual Studio command prompt for a desired target architecture (x86 or amd64).
  
=== Linux/Unix ===
+
* Add RosBE's <code>bin</code> folder to <code>PATH</code> (if you have not done that during the RosBE installation), like this:
Run:
+
<syntaxhighlight lang="dos">
<syntaxhighlight lang="bash">
+
set PATH=C:\RosBE\Bin;%PATH%
configure.sh
 
cd output-MinGW-i386
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
=== Windows or ReactOS ===
+
* Set the <code>M4</code> and <code>BISON_PKGDATADIR</code> environment variables:
Run:
 
 
<syntaxhighlight lang="dos">
 
<syntaxhighlight lang="dos">
configure.cmd
+
set M4=C:\RosBE\Bin\m4.exe
cd output-MinGW-i386
+
set BISON_PKGDATADIR=C:\RosBE\share\bison
 
</syntaxhighlight>
 
</syntaxhighlight>
After executing, folder <tt>output-MinGW-i386</tt> will be created in root of ReactOS tree. You will be redirected to it.
 
If you want to build in a different folder, cd to that folder first and then execute
 
<code>
 
<path_to_source>\configure.cmd
 
</code>
 
  
configure.cmd currently supports the following options:
+
'''NOTE:''' <code>C:\RosBE</code> is an example path of RosBE. You may choose a different one.
<tt>/?</tt> displays help,
 
<tt>Codeblocks</tt> creates a CodeBlocks solution,
 
<tt>Eclipse</tt> creates an Eclipse solution,
 
<tt>Makefiles</tt> creates (n)make files,
 
<tt>clang</tt> Uses clang instead of gcc,
 
<tt>VSSolution</tt> Creates a Visual Studio solution,
 
<tt>RTC</tt> - enables extra runtime checks
 
  
You can additionally specify any number of cmake command line options, like "-DSYMBOL=VALUE".
+
==== Windows/Clang ====
 +
* Same as MSVC, but also ensure that <code>clang-cl.exe</code> and other LLVM tools are added to <code>PATH</code>
  
=== Building ReactOS on Windows or ReactOS* ===
+
=== 2. Obtain the source code ===
From the build folder (e.g. reactos\output-MinGW-i386) entr the following command:
+
<syntaxhighlight lang="bash">
<code>
+
  git clone https://github.com/reactos/reactos.git
ninja COMMANDS
+
</syntaxhighlight>
</code>
 
  
Replace "COMMANDS" with the desired build commands, such as <code>bootcd</code> or <code>livecd</code>, listed below:
+
=== 3. Do the "configure" step ===
 +
Before building the output location must be created and prepared. This is an easy step and involves only one command. This command is located in the root of recent revisions of the source code and can be run either from the root directory itself or any other directory you want the build your sources in. Please make sure you are running it from '''within a prepared build environment (step 1)'''.
  
<small>* Perhaps, some functions of RosBE may not work on ReactOS. If so, please have a look on our [http://jira.reactos.org/ Jira] page whether this problem is already reported or not.</small>
+
==== Windows or ReactOS ====
 +
<syntaxhighlight lang="dos">
 +
configure.cmd [CMake generator] [Additional CMake options]
 +
</syntaxhighlight>
  
=== Building ReactOS on Unix/Linux ===
+
CMake generator is one of the following:
<code>
+
* <code>Ninja (default)</code> use Ninja as a CMake backend
ninja COMMANDS
+
* <code>VSSolution</code> use MSBuild/sln file as a CMake backend (for working with the source code inside Visual Studio)
</code>
 
Combining the above steps together:
 
Replace "COMMANDS" with the desired build commands, such as <code>bootcd</code> or <code>livecd</code>, listed below:
 
  
== Commands ==
+
==== *nix ====
 +
<syntaxhighlight lang="bash">
 +
configure.sh [Additional CMake options]
 +
</syntaxhighlight>
  
After you have started a Build Environment Command Prompt, there are certain commands available.
+
==== Additional options ====
  
=== Invoking a build ===
+
Additional CMake command line options may be passed in this format: <code>-DOPTION=VALUE</code>.
 +
Available options:
  
<code>'''ninja'''</code> or <code>'''ninja all'''</code>
+
* <code>ARCH</code> target architecture. Either "i386" (default), "amd64" or "arm".
 +
* <code>SARCH</code> architecture flavor. For i386 "pc" (default), "pc98" or "xbox" values are supported
 +
* <code>ENABLE_ROSTESTS</code> include tests in the build. Either "0" (default) or "1".
 +
* <code>ENABLE_ROSAPPS</code> include extra utilities in the build. Either "0" (default) or "1".
 +
* <code>PCH</code> enable [https://en.wikipedia.org/wiki/Precompiled_header precompiled headers] to increase the build speed. NOTE: may consume 7-15GB more space. Defaults to "1" for MSVC and "0" for GCC.
 +
* <code>USE_CLANG_CL</code> use clang-cl compiler instead of cl (only on Windows). Either "0" (default) or "1".
 +
* <code>NO_REACTOS_BUILDNO</code> do not include commit hash and date in the image. This allows to avoid recompiling the image when date changes. Either "0" (default) or "1".
  
This command builds all binaries of ReactOS. They will be placed in the created output directory created by the configure command. (default: ''output-MinGW-i386/reactos'')
+
So to configure an MSVC build with ninja and rosapps and rostests, you would use:
All source files, which did not change since the last build, will not be built again.
+
<syntaxhighlight lang="dos">
 +
configure.cmd -DENABLE_ROSTESTS=1 -DENABLE_ROSAPPS=1
 +
</syntaxhighlight>
  
<code>'''ninja bootcd'''</code>
+
=== 4. Start the build ===
 +
This step depends on what has been chosen as a CMake generator.
  
This command works like ''make'', but also generates a bootable ReactOS ISO file (''bootcd.iso'') placed into the output directory.
+
==== Ninja ====
It is wise to tag your Boot-CDs with the revision they were built from if you need to keep many ReactOS ISOs.
 
  
<code>'''ninja livecd'''</code>
+
From the build folder (e.g. reactos\output-MinGW-i386) enter the following command:
 
+
<syntaxhighlight lang="dos">
This command generates ''livecd.iso'' in the output directory. This is the ReactOS Live-CD that runs completely from the CD-ROM.
+
ninja [targets]
 
+
</syntaxhighlight>
<code>'''ninja hybridcd'''</code>
 
 
 
This command generates ''hybridcd.iso'' in the output directotry. This is a hybrid cd of ReactOS
 
 
 
<!--
 
=== Other ===
 
  
'''clean'''
+
Available targets are:
This command cleans all files of your working copy except the generated ISO files (if any). The next build you make will be completely clean then. Any parameters will recognized as module name and only this module will be cleaned then. -->
+
* <code>bootcd</code> creates an installation ISO to install ReactOS on a VM or PC.
<!-- to be continued -->
+
* <code>livecd</code> creates a live CD ISO to try ReactOS without installing.
 +
* <code>all</code> builds all binaries of ReactOS. ISO files are not created though.
 +
* <code>clean</code> cleans all files of your working copy except the generated ISO files (if any).
 +
* Any other binary file ReactOS consists of, for example <code>kernel32</code> or <code>ntoskrnl</code>
  
== Adding modules to the build process ==
+
==== VSSolution (Visual Studio) ====
  
There are several modules you can add to the build process. For example ''rosapps'' contains some additional applications not included by default.
+
{{Warning|Visual Studio (VSSolution) build cannot currently produce a bootable ISOs so use it for working with individual user-mode apps (like notepad, rapps or paint). For building bootcd or livecd configuration, please use Ninja option.}}
 +
''For this example we are going to see how to build [https://github.com/reactos/reactos/tree/master/base/applications/rapps rapps] from Visual Studio 2019.''
  
The page [[Building Modules]] describes, which modules exist and how to add them to the build process.
+
* If configure step went well, this message should appear:
 +
<pre>
 +
Configure script complete! You can now use msbuild or open REACTOS.sln.
 +
</pre>
 +
* There should now be a REACTOS.sln in your build folder (Which contains ALL projects!)
 +
* Since rapps has the cmake [[https://git.reactos.org/?p=reactos.git&a=search&h=HEAD&st=grep&s=project%28rapps%29 <code>project(rapps)</code>]] macro, there will also be a smaller solution just for rapps at <code>base\applications\rapps\rapps.sln</code>
 +
* Open this solution, and expand <code>base\rapplications\rapps</code>
 +
* Right click rapps, choose '''Set as Startup Project'''
 +
[[File:Set as Startup Project.png]]
 +
* Press '''Debug->Start Debugging''' in the menu, or the hotkey that is displayed behind it (usually <kbd>F5</kbd>)
  
 
== See also ==
 
== See also ==
* '''[http://www.reactos.org/development/build-environment Build Environment] – another tutorial how to build ReactOS '''
+
* [[Installing ReactOS]]
* [[Building with MSVC]]
+
* [[Developing ReactOS with Visual Studio]]
 
* [[Building MINGW-w64]]
 
* [[Building MINGW-w64]]
* [http://www.reactos.org/forum/viewtopic.php?f=22&t=11000 Building with Ninja] latest build method, RosBE v2.1
+
* (historical) [[RBuild]]
  
 
[[Category:Building]]
 
[[Category:Building]]
 
[[Category:Tutorial]]
 
[[Category:Tutorial]]

Latest revision as of 15:28, 11 February 2023

This page describes the steps necessary to build ReactOS.
ReactOS supports building on different operating systems and with different compilers. Currently GCC, MSVC and LLVM/Clang can be used.

The build process differs depending your operating system and the compiler of choice.
Each build step in the tutorial is separated by OS/compiler when necessary. Choose ones which fit your configuration.

Which compiler to use

  • GCC is currently a recommended option as the most simple to use.
  • MSVC compiler can be used for better debugging capabilities (only MSVC builds support windbg debugger).
  • Clang support is currently experimental and not advised unless you know what are you doing.

Prerequisites

Visual Studio installation remarks
  • Download the Visual studio 2017 community edition (or later).
When selecting the options, be sure to at least include Desktop development with C++.

Desktop development

  • Ensure you have started visual studio at least once, and you are able to create a working c++ project.
To validate this, choose Create a new project, choose Console App, and use all default options.
  • While installing RosBE, you may choose the option Add BIN folder to PATH variable (may be added later manually).

RosBE BIN folder.png

Imbox notice.png

Notice: It is recommended to disable antivirus software before proceeding (or adding a build folder to exceptions), because some AVs may detect ReactOS' system files (in particular, crtdll.dll or csrss.exe) as being infected.

TL;DR

<inside RosBE command prompt>
git clone https://github.com/reactos/reactos
cd reactos
configure.cmd
cd output-MinGW-i386
ninja bootcd livecd

Building instructions

1. Prepare a command prompt

Windows/GCC or ReactOS/GCC

  • Just use the RosBE command prompt (from the Start menu)

*nix/GCC

  • Invoke RosBE.sh script

*nix/Clang

  • Invoke RosBE.sh script, ensure clang is available in $PATH

Windows/MSVC

  • Open a Visual Studio command prompt for a desired target architecture (x86 or amd64).
  • Add RosBE's bin folder to PATH (if you have not done that during the RosBE installation), like this:
set PATH=C:\RosBE\Bin;%PATH%
  • Set the M4 and BISON_PKGDATADIR environment variables:
set M4=C:\RosBE\Bin\m4.exe
set BISON_PKGDATADIR=C:\RosBE\share\bison

NOTE: C:\RosBE is an example path of RosBE. You may choose a different one.

Windows/Clang

  • Same as MSVC, but also ensure that clang-cl.exe and other LLVM tools are added to PATH

2. Obtain the source code

  git clone https://github.com/reactos/reactos.git

3. Do the "configure" step

Before building the output location must be created and prepared. This is an easy step and involves only one command. This command is located in the root of recent revisions of the source code and can be run either from the root directory itself or any other directory you want the build your sources in. Please make sure you are running it from within a prepared build environment (step 1).

Windows or ReactOS

configure.cmd [CMake generator] [Additional CMake options]

CMake generator is one of the following:

  • Ninja (default) use Ninja as a CMake backend
  • VSSolution use MSBuild/sln file as a CMake backend (for working with the source code inside Visual Studio)

*nix

configure.sh [Additional CMake options]

Additional options

Additional CMake command line options may be passed in this format: -DOPTION=VALUE. Available options:

  • ARCH target architecture. Either "i386" (default), "amd64" or "arm".
  • SARCH architecture flavor. For i386 "pc" (default), "pc98" or "xbox" values are supported
  • ENABLE_ROSTESTS include tests in the build. Either "0" (default) or "1".
  • ENABLE_ROSAPPS include extra utilities in the build. Either "0" (default) or "1".
  • PCH enable precompiled headers to increase the build speed. NOTE: may consume 7-15GB more space. Defaults to "1" for MSVC and "0" for GCC.
  • USE_CLANG_CL use clang-cl compiler instead of cl (only on Windows). Either "0" (default) or "1".
  • NO_REACTOS_BUILDNO do not include commit hash and date in the image. This allows to avoid recompiling the image when date changes. Either "0" (default) or "1".

So to configure an MSVC build with ninja and rosapps and rostests, you would use:

configure.cmd -DENABLE_ROSTESTS=1 -DENABLE_ROSAPPS=1

4. Start the build

This step depends on what has been chosen as a CMake generator.

Ninja

From the build folder (e.g. reactos\output-MinGW-i386) enter the following command:

ninja [targets]

Available targets are:

  • bootcd creates an installation ISO to install ReactOS on a VM or PC.
  • livecd creates a live CD ISO to try ReactOS without installing.
  • all builds all binaries of ReactOS. ISO files are not created though.
  • clean cleans all files of your working copy except the generated ISO files (if any).
  • Any other binary file ReactOS consists of, for example kernel32 or ntoskrnl

VSSolution (Visual Studio)

Icon speedy deletion.png Warning: Visual Studio (VSSolution) build cannot currently produce a bootable ISOs so use it for working with individual user-mode apps (like notepad, rapps or paint). For building bootcd or livecd configuration, please use Ninja option.


For this example we are going to see how to build rapps from Visual Studio 2019.

  • If configure step went well, this message should appear:
Configure script complete! You can now use msbuild or open REACTOS.sln.
  • There should now be a REACTOS.sln in your build folder (Which contains ALL projects!)
  • Since rapps has the cmake [project(rapps)] macro, there will also be a smaller solution just for rapps at base\applications\rapps\rapps.sln
  • Open this solution, and expand base\rapplications\rapps
  • Right click rapps, choose Set as Startup Project

Set as Startup Project.png

  • Press Debug->Start Debugging in the menu, or the hotkey that is displayed behind it (usually F5)

See also