Difference between revisions of "User:Oldman"

From ReactOS Wiki
Jump to: navigation, search
m
(Deleted all the guides here, now that they have been move to individual guides.)
(Tag: Replaced)
 
Line 1: Line 1:
 
<span style="font-size:130%;">'''NOTE''': The layman's guides have been migrated and separated into [[User:Oldman/A_layman's_guide | Individual Layman's guides]]</span>
 
<span style="font-size:130%;">'''NOTE''': The layman's guides have been migrated and separated into [[User:Oldman/A_layman's_guide | Individual Layman's guides]]</span>
  
 +
This one page of all the guides has now been removed
  
The guides on this page will be removed, so if you have book-marked this page, then please alter your book-marks for the new pages.
+
<hr>
  
<h2>A layman's guide - <span style="font-size:150%;color:#600080;">Getting an ISO to test</span></h2>
 
 
This should not be needed, but this is a layman's guide, so I will describe where to get your ReactOS iso from.
 
 
===Release ISO===
 
On the front page at '''<nowiki>https://www.reactos.org/</nowiki>''' on the right hand side of the navigation bar, you will find two download buttons <sup>[<span style="color:#600080">'''No1'''</span>]</sup>, click on either button and it will take you to the '''Download''' page for the release ISOs, where you have a choice of down loading a bootcd or a livecd, but there is also a link to the daily build ISOs page, further down this page <sup>[<span style="color:#600080">'''No2'''</span>]</sup>.
 
<gallery widths="416px" heights="325px" paddings="0px">
 
File:Download-No1a-FrontPage.png|[<span style="color:#600080">'''No1'''</span>] Front page links.
 
File:Download-fromNo1a-frontpage.png |[<span style="color:#600080">'''No2'''</span>] The Release ISO download page, with a link to the daily builds page.
 
</gallery>
 
 
<div style="border:1px solid #dd0000;padding:5px">'''Note:'''
 
If the latest release ISOs, are more then a week old, it is better not use them for testing, because they very quickly become out of date, due to the continual development of ReactOS.</div>
 
 
===Latest build ISO===
 
On the front page, if you scroll down a little, you will see over on the right side of the page, underneath <span style="font:normal 200% monospace">&nbsp;and more...</span>, the box shown in image <span style="color:#600080">'''No3a'''</span>.
 
<gallery widths="372px" heights="323px" paddings="0px">
 
File:Download-Nob1-FrontPage.png |[<span style="color:#600080">'''No3a'''</span>]  ‎
 
File:Download-Nob2-FrontPage.png |[<span style="color:#600080">'''No3b'''</span>] Download link.
 
</gallery>
 
If you click on the <span style="color:#0050c0">'''Daily builds'''</span> button, it will close the <span style="color:#0050c0">'''Gallery'''</span> section and open the <span style="color:#0050c0">'''Daily builds'''</span> section <sup>[<span style="color:#600080">'''No3b'''</span>]</sup>, to reveal the '''Download here!''' button.
 
If you then click on the '''Download here!''' button, it will take you to the Trunk Builds page <sup>[<span style="color:#600080">'''No4'''</span>]</sup>.
 
<gallery widths="800px" heights="487px" paddings="0px">
 
File:Download_Trunk_Builds.png |[<span style="color:#600080">'''No4'''</span>]‎ Page for the ‎daily (trunk) builds.
 
</gallery>
 
 
 
'''Trunk Builds page explained <small>[<span style="color:#600080">'''No4'''</span>]</small>''':
 
 
'''Revision''' - The input box shows the number of the last created ISO. The left and right arrows decrease or increase the number. You can also type a number into the box and press Enter on your keyboard or press the '''Search''' button. This is useful when you want to find a ISO from the past. '''Browse all created Builds''' button with take you away from this page to https://iso.reactos.org/, where there are folders for bootcd and livecd ISOs. Bootcd ISOs go back to Mid Jan 2008, newest at the bottom and the oldest at the top. Livecd ISOs currently only go back to April 2017 (this may alter each year).
 
 
'''Image Types''' - The check boxes here are only useful when you are searching for a particular build from the past. You can uncheck the types you do not want. The '''Search''' button updates the list of files.
 
 
'''<span style="color:#0050c0">Debug Boot CDs</span>'''
 
*reactos-bootcd-0.4.7-dev-575-g48b2714-x86-gcc-lin-dbg.7z
 
*reactos-bootcd-0.4.7-dev-575-g48b2714-x86-msvc-win-dbg.7z
 
'''<span style="color:#0050c0">Debug Live CDs</span>'''
 
*reactos-livecd-0.4.7-dev-575-g48b2714-x86-gcc-lin-dbg.7z
 
*reactos-livecd-0.4.7-dev-575-g48b2714-x86-msvc-win-dbg.7z
 
'''<span style="color:#0050c0">Release Boot CDs</span>'''
 
*reactos-bootcd-0.4.7-dev-575-g48b2714-x86-gcc-lin-rel.7z
 
'''<span style="color:#0050c0">Release Live CDs</span>'''
 
*reactos-livecd-0.4.7-dev-575-g48b2714-x86-gcc-lin-rel.7z
 
 
'''Size''' and '''Last changed''', are self explanatory.
 
 
 
<div style="border:1px solid #dd0000;padding:5px">'''Note:''' On the website there are several possibly confusing words, such as '''Trunk Builds''', '''Daily Builds''', '''Nightly Builds''', '''CDs''' and on a link button '''Latest Build!''', these all refer to the 7zipped ISO files that can be down-loaded at the page shown in image <span style="color:#600080">'''No4'''</span>.
 
</div>
 
 
 
<p style="font-size:150%;border-top:3px solid #600080;"></p>
 
 
 
<h2>A layman's guide - <span style="font-size:150%;color:#0000ff;">How to compile ReactOS.</span></h2>
 
 
This guide shows you how to make your own working environment, down load the ReactOS source code and then compile it using the '''R'''eact'''os B'''uild''' E'''vironment. The main section covers Windows and the subsection covers unix.
 
 
===Setting up a local working environment===
 
 
You will need to install '''git''' for Windows from '''https://git-for-windows.github.io/''' and '''TortoiseGit''' from '''https://tortoisegit.org/'''.
 
 
Next you will need to create a master folder to keep all the next folders in one place. This folder can be created in C: or D: (or any other drive partition), for example '''D:\ReactOSDevelopment''' or '''C:\ROS'''.
 
 
Create the following folders in your master folder:
 
 
1.  '''\source'''  (the name does not matter - you will download the source tree into this folder).
 
 
2.  '''\compiled''' (the name does not matter - this is the output folder where the binaries are complied to and the ISO is created).
 
 
3.  '''\RosBE'''    (this is where you will install RosBE).
 
 
You should now have something like the following examples.
 
 
Example No1
 
 
'''C:\ROS\source'''
 
 
'''C:\ROS\compiled'''
 
 
'''C:\ROS\RosBE'''
 
 
or
 
 
Example No2
 
 
'''D:\ReactOS_Development\Source'''
 
 
'''D:\ReactOS_Development\Compiled'''
 
 
'''D:\ReactOS_Development\RosBE'''
 
 
Using example No2, within '''D:\ReactOS_Development\''' create a '''Compiled''' folder, a '''RosBE''' folder and a '''Source''' folder.
 
Next, navigate into '''D:\ReactOS_Development\Source''' and right click within the folder, then select '''Git Clone''', then in the next window, enter this url '''<nowiki>https://github.com/reactos/reactos.git</nowiki>'''; this will create a '''reactos''' folder and download the current source tree into it.
 
 
I have noticed this behaviour with Git; if you first copy the url, then click in the source folder, you will find that Git has put the copied url in the '''Url''' input and put the path to your source folder with the addition of reactos, in the '''Directory''' input.
 
See <sup>[<span style="color:#0000ff">'''1'''</span>]</sup> <sup>[<span style="color:#0000ff">'''2'''</span>]</sup> <sup>[<span style="color:#0000ff">'''3a'''</span>]</sup> <sup>[<span style="color:#0000ff">'''3b'''</span>]</sup>  <sup>[<span style="color:#0000ff">'''4'''</span>]</sup> in the '''Getting the source with Git''' section below.
 
 
For how to update your local source, see the subsection '''[[#Updating a local source tree with Git|Updating a local source tree with Git]]'''.
 
 
Having downloaded the source you will now need to download and install the ReactOS Build Environment <sup>[<span style="color:#0000ff">'''5'''</span>]</sup> <sup>[<span style="color:#0000ff">'''6'''</span>]</sup> <sup>[<span style="color:#0000ff">'''7'''</span>]</sup>
 
(a link to the latest version <small>(''Windows and Unix'')</small> can be found here: '''https://www.reactos.org/wiki/ReactOS_Build_Environment''') into '''D:\ReactOS_Development\RosBE'''.
 
 
'''Note''': if want to have a script do most of the above work for you, then there is a  '''[[#Windows - Create the Tutorial working environment|script here]]''' to do just that.
 
 
===Compiling the source===
 
 
To continue with my example; start RosBE, and from it's command prompt: <sup>[<span style="color:#0000ff">'''8'''</span>]</sup> ('''Note''': If you did not install '''RosBE''' with the desktop shortcut option selected, then open a command prompt window and navigate to '''D:\ReactOS_Development\RosBE''' and type '''RosBE''' to start it.) and within RosBE,
 
 
'''1'''.  Navigate to '''D:\ReactOS_Development\Compiled''' and type '''D:\ReactOSDevelopment\Source\reactos\configure ninja'''
 
 
'''2'''. Still within '''D:\ReactOS_Development\Compiled''' type '''ninja bootcd'''
 
 
or
 
 
'''3'''.  Still within '''D:\ReactOS_Development\Compiled''' type '''ninja livecd'''
 
 
or
 
 
'''4'''.  Still within '''D:\ReactOS_Development\Compiled''' type '''ninja hybridcd'''
 
 
or if want all three ISO images
 
 
'''5'''.  Still within '''D:\ReactOS_Development\Compiled''' type '''ninja bootcd livecd hybridcd'''
 
 
 
Now you should find the '''bootcd''' and/or the '''livecd''' and/or '''hybridcd''' in '''D:\ReactOS_Development\Compiled\reactos'''.
 
 
If you have problems compiling after you have updated your local source tree, try typing '''ninja clean''' ('''D:\ReactOS_Development\Compiled\ninja clean''') and then start again at step '''1''' above.
 
 
===Compiling - Screenshots===
 
 
====Getting the source with Git====
 
<gallery widths="429px" heights="545px" paddings="0px">
 
File:git-clone-1.png|[<span style="color:#0000ff">'''1'''</span>] Right click on the source folder and select '''Git Clone..''' in the drop down menu.
 
</gallery>
 
 
The following window will then open.
 
 
<gallery widths="547px" heights="381px" paddings="0px">
 
File:Git-clone-2.png|[<span style="color:#0000ff">'''2'''</span>] If the URL is correct (https://github.com/reactos/reactos.git) and the Directory (for the source) is correct, then the rest can be left as they are. Click on the '''OK''' button to start the download process.
 
</gallery>
 
 
<gallery widths="505px" heights="334px" paddings="0px">
 
File:source-progress-1.png|[<span style="color:#0000ff">'''3a'''</span>]  This shows the beginning of the download process.
 
File:source-progress-2.png|[<span style="color:#0000ff">'''3b'''</span>]  This shows Git downloading the files.
 
</gallery>
 
 
<gallery widths="505px" heights="334px" paddings="0px">
 
File:source-completed.png|[<span style="color:#0000ff">'''4'''</span>] This is shows a source download completed.
 
</gallery>
 
 
 
====Updating a local source tree with Git====
 
<gallery widths="499px" heights="450px" paddings="0px">
 
File:Git-pull-1.png| Right click on your source folder, then select '''TortoiseGit''', then '''Pull...'''
 
File:Git-Pull-2.png| If this window has the same settings as in the above, then leave it as it is and click '''OK'''
 
</gallery>
 
<gallery widths="505px" heights="334px" paddings="0px">
 
File:Git-pull-3.png| This shows a completed update of the source folder from reactos.git
 
</gallery>
 
 
 
==== Configuring and installing RosBE ====
 
<gallery widths="503px" heights="321px" paddings="0px">
 
File:rosbe-1.png|[<span style="color:#0000ff">'''5'''</span>] Choosing the installation folder for RosBE.
 
</gallery>
 
 
<gallery widths="502px" heights="327px" paddings="0px">
 
File:rosbe-2.png|[<span style="color:#0000ff">'''6'''</span>] Choosing the folder where the source code is to be found.
 
</gallery>
 
 
<gallery widths="503px" heights="386px" paddings="0px">
 
File:rosbe-3.png|[<span style="color:#0000ff">'''7'''</span>] Choosing a Desktop icon.
 
</gallery>
 
 
 
==== Configuring and installing RosBE ====
 
<gallery widths="503px" heights="321px" paddings="0px">
 
File:rosbe-1.png|[<span style="color:#0000ff">'''5'''</span>] Choosing the installation folder for RosBE.
 
</gallery>
 
 
<gallery widths="502px" heights="327px" paddings="0px">
 
File:rosbe-2.png|[<span style="color:#0000ff">'''6'''</span>] Choosing the folder where the source code is to be found.
 
</gallery>
 
 
<gallery widths="503px" heights="386px" paddings="0px">
 
File:rosbe-3.png|[<span style="color:#0000ff">'''7'''</span>] Choosing a Desktop icon.
 
</gallery>
 
 
====Compiling====
 
 
<gallery widths="715px" heights="546px" paddings="0px">
 
File:RosBEcompiling.png|[<span style="color:#0000ff">'''8'''</span>] RosBE in action.
 
</gallery>
 
In the screenshot of RosBE, you can see that the working directory as been changed from '''source''' to '''compiled''', then '''configure ninja''' as been executed and completed. The command line now shows '''ninja bootcd''' waiting to be executed.
 
 
 
===<span style="color:#0000ff">How to compile ReactOS - '''Unix subsection'''</span>===
 
 
The ReactOS Build Environment requires the following software to be installed on Unix systems:
 
 
* '''as'''
 
* '''bison'''
 
* '''curl'''
 
* '''flex'''
 
* '''gcc'''
 
* '''git'''
 
* '''g++'''
 
* '''make'''
 
* '''makeinfo'''
 
* '''pkg-config'''
 
* '''python'''
 
* '''zlib'''
 
 
There is a script in the unix section of '''[[#Software_checker-installer_for_RosBE |Miscellaneous]]''', which can automate the checking for and installation of the above software.
 
 
===Setting up a local working environment===
 
 
You will now need to download the ReactOS Build Environment (RosBE), from  '''https://www.reactos.org/wiki/ReactOS_Build_Environment'''
 
 
'''Example:'''
 
 
Unpack the RosBE installation files to '''/home/RosBE-Unix-2.1.2''' directory.
 
 
Create the following folders '''/home/RosBuild''' then '''/home/RosBuild/RosBE''' (install RosBE in this folder).
 
 
'''Note:''' The default directory for RosBE, is '''/usr/local/RosBE''', if you prefer, you can use that.
 
 
To continue with my example; Open the folder '''/home/RosBE-Unix-2.1.2''' and right click within <sup>[<span style="color:#0000ff">'''9'''</span>]</sup>, for the menu, '''Window''' - '''Terminal Here''' <sup>[<span style="color:#0000ff">'''10'''</span>]</sup>.
 
 
In the terminal window, run the builder script by typing '''./RosBE-Builder.sh'''.  If it reports any missing tools <sup>[<span style="color:#0000ff">'''11'''</span>]</sup>, you will need to install them (see list above).
 
 
Then run the script as before, and if it reports all tools '''OK''' <sup>[<span style="color:#0000ff">'''12'''</span>]</sup>, then you can continue.
 
 
To follow my example, type '''/home/RosBuild/RosBE''' for the install directory and then follow the instructions from the running script.
 
 
If all went well, then it will ask you about creating a shortcut, just follow the instructions.
 
 
I created the shortcut in '''/home''' then copied it onto the desktop and checked to see if it ran RosBE.
 
 
To populate your source folder, you will need to open a terminal window within the empty source folder; right click - '''Window''' - '''Terminal Here''', then at the command prompt, type: '''git clone https://github.com/reactos/reactos.git'''. This will create a folder called '''reactos''' and download the main source code.
 
 
To get the revision number, right click on the reactos folder and select '''Window''' - '''Terminal Here''', then at the command prompt, type: '''git describe''', which will display something like this '''0.4.7-dev-532-g3cd76b91b5'''.
 
 
The alternative to the 'Right click-Window-Terminal Here' method, is to type the full address, eg. '''/home/RosBuild/source'''.
 
 
To update the source code, right click within the reactos folder and select '''Window''' - '''Terminal Here''', then at the command prompt type: '''git pull https://github.com/reactos/reactos.git'''
 
 
'''NOTE''': You must be '''actually in''' the '''source''' folder to clone and '''actually in''' the '''reactos''' folder to update the source or get the revision number.
 
 
There is also a script in the '''[[#Create the Tutorial working environment|Miscellaneous]]''' unix section, that can automate the setting up of a working environment.
 
 
===Compiling the source===
 
 
Start RosBE and at the terminal command prompt type '''cd /home/RosBuild/compiled''' (or the directory that you want ReactOS to be built into).
 
Then type '''/home/RosBuild/source/reactos/configure.sh'''. When the script finishes, type '''cd /home/RosBuild/compiled/reactos/''' and then '''ninja livecd''' or '''ninja bootcd'''
 
 
====Screenshots====
 
 
<gallery widths="435px" heights="234px" paddings="0px">
 
File:Terminalinwin-1.png|[<span style="color:#0000ff">'''9'''</span>] Move your mouse pointer into the window and right button click.
 
</gallery>
 
<gallery widths="482px" heights="468px" paddings="0px">
 
File:Terminalwin-2.png|[<span style="color:#0000ff">'''10'''</span>] Select as shown for a terminal window.
 
</gallery>
 
 
<gallery widths="744px" heights="430px" paddings="0px">
 
File:RosBE-Builder-1.png|[<span style="color:#0000ff">'''11'''</span>] RosBE installation script (RosBE-Builder.sh) running in a terminal window, showing missing dependencies.
 
</gallery>
 
<gallery widths="744px" heights="430px" paddings="0px">
 
File:RosBE-Builder-2.png|[<span style="color:#0000ff">'''12'''</span>] RosBE installation script (RosBE-Builder.sh) running in a terminal window, showing dependencies all found.
 
</gallery>
 
 
 
<p style="font-size:150%;border-top:3px solid #0000ff;"></p>
 
 
 
<h2>A layman's guide - <span style="font-size:150%;color:#b60000;">How to get a debug log.</span></h2>
 
 
This guide will show you how to get a debug log, using the '''Debug''' mode in real hardware and with a virtual machine using com0com (Windows) or tty0tty (unix), using the built in ReactOS debugger. The difference with the other debug modes is explained in '''Variations'''
 
 
===Debug ISOs===
 
 
reactos-bootcd-0.4.7-dev-581-g9c790df-x86-gcc-lin-dbg.7z
 
 
reactos-livecd-0.4.7-dev-575-g48b2714-x86-gcc-lin-dbg.7z
 
 
 
reactos-bootcd-0.4.7-dev-575-g48b2714-x86-msvc-win-dbg.7z
 
 
reactos-livecd-0.4.7-dev-575-g48b2714-x86-msvc-win-dbg.7z
 
 
 
'''Explanation:'''
 
 
'''reactos-bootcd''' - '''0.4.7''' - '''dev''' - '''581-g9c790df''' - '''x86-gcc-lin-dbg'''.7z
 
 
'''reactos-bootcd''' = type of ISO ('''boot''' for installing, '''live''' for running OS without installing).
 
 
'''0.4.7''' = The number of the next release. The number changes every time a release branch is created, so when the 0.4.7 was branched for release, the number on the daily/latest ISOs became 0.4.8. And when the 0.4.8 was branched for release, the number on the daily/latest ISOs became 0.4.9. Now the 0.4.9 is branched, the number on the daily/lastest ISOs are numbered 0.4.10.
 
 
'''dev''' = development
 
 
'''581-g9c790df''' = identifies the commit and the committer.
 
 
'''x86-gcc-lin-dbg''' = '''x86''' (32bit OS) - '''gcc''' (compiler) - '''lin''' (built using Linux) - '''dbg''' (debug build)
 
 
reactos-bootcd-0.4.7-dev-575-g48b2714-x86-'''msvc-win'''-dbg.7z
 
 
'''msvc-win''' = '''msvc''' (compiler) - '''win''' (built using Windows)
 
 
For normal users, the ISOs built with '''gcc''' are the ones to go for. You may need a copy of MSVC to make full use of the '''msvc-win''' builds.
 
 
===Stages of the installation of ReactOS===
 
It may be helpful to understand the stages of the installation of ReactOS.
 
 
'''First stage:'''
 
 
When the installation CD (bootcd) is run, the bootloader asks you to '''press any key to install''' (real hardware)
 
 
The OS will first load itself into memory, then you are presented with the '''Language''' setup window, then 2 more windows, then '''Device settings''' window, then choose '''Hard drive partition''' window, then '''format''' window, then '''confirm format''' window. then '''choose directory''' window. then 2 more windows, then '''bootloader choice''' window. In the last window you are asked to '''remove media and press Enter'''. The computer now reboots.
 
 
'''Second stage:'''
 
 
The bootloader shows the '''Boot options choice''' window, then boots, loads device drivers, then shows the '''setup''' window, after that there are more configuration windows (when testing you can press '''Enter''' at all these windows), before it finally reboots.
 
 
'''Third stage:'''
 
 
It now boots up into desktop and displays the driver install wizard, if it finds any hardware without a driver.
 
 
'''NOTE:'''
 
 
Debug output only starts when the OS is loaded into memory, but just before it loads the drivers.
 
 
When installing (First stage), debug output is turned on by default and can only be captured through a null modem serial cable connect to a second computer, but once ReactOS is installed (Second stage and normal usage), you will have a choice of how to record debug output, from the boot menu. See <sup>[<span style="color:#b60000">'''1'''</span>]</sup> in '''Screenshots''' section below. 
 
 
===Hardware requirements:===
 
* A test computer with a serial port.
 
* A second computer with a serial port and Putty installed (or similar app).
 
* A nullmodem cable to connect both computers.
 
===Software===
 
Win32 Putty - http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html You will also find the source code for Windows and Unix at this link, but Linux users may be able to get Putty through their Package Manager.
 
 
=== Setting up Putty. ===
 
There are some vital settings in Putty, which need to be set, so that Putty can capture a debug log.
 
In putty go to '''Category''' and select '''Session''', then set the following inputs to these values:
 
<br />
 
'''Serial line''' = '''COM1'''
 
<br />
 
'''Speed''' = '''115200'''
 
<br />
 
'''Connection type''' = '''Serial'''
 
 
Back to '''Category''' and select '''Logging''', in '''Session logging:''' check '''All session output'''. Note where Putty saves the log file and change if required; use the '''Browse''' button for the destination folder.
 
 
See in '''Screenshots''' <sup>[<span style="color:#b60000">'''2'''</span>] [<span style="color:#b60000">'''3'''</span>]</sup> below for visual information.
 
 
Save the above changes in putty, with a name of your choice, in '''Saved Sessions''', then use the '''Save''' button. It can then be loaded the next time you use Putty, by using the '''Load''' button. Note: logging is started by using the '''Open''' button.
 
 
=== The ReactOS debugger ===
 
The ReactOS debugger has some commands that can be used from the command line; all of the commands are typed into the ReactOS test computer, but will be viewed in the terminal window (i.e putty) on the second computer. To enter a command, press the hotkey combination of '''Tab'''<small>+</small>'''k''', which halts the system and gives you the command prompt which looks like this: '''kdb:>''' where you can then enter the command.
 
 
==== Commands: ====
 
'''Tab'''<small>+</small>'''k''' - this command halts the system so you can enter commands into the debugger.
 
<br />
 
'''bt''' - this command gives a backtrace; use it when ROS enters the debugger (see below).
 
<br />
 
'''cont''' - this is short for continue.
 
<br />
 
'''set condition <big><big>*</big></big> first always''' - this command tells ROS to enter the debugger on the first exception.
 
 
The following is an example of when ROS enters the debugger (see also in the <sup>[<span style="color:#b60000">'''4'''</span>]</sup> screenshot below):
 
<br />
 
<span style="color:#ffffff;background:#000000">Entered debugger on last-chance exception (Exception Code: 0xc0000001) (Unknown/User defined exception)<br />kdb></span>
 
 
=== Getting a backtrace: ===
 
By looking in the Putty window, you will see when ROS enters the debugger, when that happens, you need to enter '''bt''' at the command prompt, like so:
 
'''kdb:> bt''' <sup>[<span style="color:#b60000">'''4'''</span>]</sup> and press '''enter''' on the keyboard.
 
You may see this
 
<br />
 
'''--- Press q to abort, any other key to continue ---''' <sup>[<span style="color:#b60000">'''5'''</span>]</sup>
 
<br />
 
If you do see it, then just press any key other than q, it may show again, just repeat until you are back at the command prompt of '''kdb:>'''
 
 
=== Getting a more detailed backtrace: ===
 
When you see debug info streaming into putty <sup>[<span style="color:red">Note</span>]</sup>, then press the hotkey combination of '''Tab'''<small>+</small>'''k''' on your keyboard, then type '''set condition <big><big>*</big></big> first always''' at the command prompt and press '''enter''' on the keyboard, then type '''cont''' <sup>[<span style="color:#b60000">'''6'''</span>]</sup> and press '''enter''' on the keyboard. Setting the condition to first always, will make ReactOS enter the debugger on every exception, which it will do many times, and each time you will have to type '''bt''' then '''cont'''.
 
 
<div style="border:1px solid #dd0000;padding:5px"><span style="color:#ff0000">'''Note'''</span>: If you are testing an app, then it is better to wait until you are ready to run the app, before setting the condition to first always, else you could be overwhelmed with ReactOS entering the debugger.</div>
 
 
=== No working keyboard! ===
 
Currently <small>(Jan 2015)</small> usb support is problematic, so your keyboard may not work! If you have found that your usb keyboard does not work with ReactOS, and ReactOS bsods at or before the first input window in the installation process, but after it is running in memory, you should still be able to get a debug log by using a '''livecd debug''' version (example: '''reactos-livecd-0.4.7-dev-575-g48b2714-x86-gcc-lin-rel.7z'''). The livecd versions currently default to '''Debug''' mode, so when it boots, it will output debug info to the serial port, but you will not be able to get a '''backtrace'''!
 
 
=== Advice: ===
 
'''Do not''' use '''Tab'''<small>+</small>'''k''' and '''bt''' to get a '''backtrace''', when ReactOS does not automatically enter the debugger! If you think by doing so, you will get some more useful information for the dev's to work with (which I have done in the past), you will not, it is a waste of time, the backtrace is of no value!
 
 
Putty names the file putty.log, it would be a good idea to re-name it, because the next time that putty is run, it will over-write the file called "putty.log". I use something descriptive, in this format "'''''app name - ReactOS revision number'''''", for example "'''gimp-1.0.4 [0.4.7-dev-575-g48b2714]'''".
 
 
'''TIP:'''
 
If you find that when you use the test computer's keyboard to enter commands, nothing appears at the Command Prompt on the second (receiving) computer, then type the command on the second computer's keyboard, you then should see what you type appear at the Command Prompt.
 
 
=== Variations ===
 
'''RosDbg''' - This is only useful when ReactOS is compiled with a Microsoft compiler, which adds extra debugging code into ReactOS, which can output extra debug info. In use, the difference from '''Debug''', is in the keyboard input, where you can only use '''Tab''' <small>+</small> '''k''' on the ReactOS test computer, all other keyboard input is via the logging computer's keyboard.
 
 
'''Screen''' - In this mode, debug information is written to the screen and you will have to take photos to be able to submit the information in a JIRA Issue. Any keyboard input is done on the ReactOS test computer keyboard. The instructions for '''Debug''' mode also apply to '''Screen''' mode.
 
 
'''Log file''' - This writes all debug output to a '''debug.log''' at '''C:\reactos\''', on the ReactOS test computer's hard drive. Any keyboard input is done on the ReactOS test computer keyboard. You may, also need to use a Linux livecd to be able to recover the log file from the test computer.
 
 
=== Getting a debug log - Screenshots ===
 
 
<gallery widths="443px" heights="213px" paddings="0px">
 
File:StartMenu.png|[<span style="color:#b60000">1</span>] ReactOS boot options menu.
 
</gallery>
 
<gallery widths="456px" heights="435px" paddings="0px">
 
File:PuttyConf-1.png|[<span style="color:#b60000">2</span>] PuTTY Configuration - Session
 
File:PuttyConf-2.png|[<span style="color:#b60000">3</span>] PuTTY Configuration - Logging
 
</gallery>
 
<gallery widths="678px" heights="46px" paddings="0px">
 
File:Debugger-1.png|[<span style="color:#b60000">4</span>] Ros in the debugger showing '''bt''' entered at the command prompt.
 
</gallery>
 
<gallery widths="579px" heights="17px" paddings="0px">
 
File:Debugger-2.png|[<span style="color:#b60000">5</span>] You may see this after entering '''bt''' and after the debug info has stopped.
 
</gallery>
 
<gallery widths="445px" heights="48px" paddings="0px">
 
File:Debugger-3.png|[<span style="color:#b60000">6</span>] The debugger has been entered manually and shows  '''set condition '''*''' first always''' typed at the command prompt and '''cont'''.
 
</gallery>
 
<gallery widths="765px" heights="37px" paddings="0px">
 
File:Break.png|[<span style="color:#b60000">7</span>] If you see this, type '''o''' as shown and press enter on your keyboard.
 
</gallery>
 
 
=== Getting a debug log from VirtualBox ===
 
This section covers a simple VirtualBox setup using com0com or tty0tty as a virtual null modem cable to connect to Putty; all running on the same computer, no need for a real null modem cable and a second computer.
 
 
VirtualBox for Windows, Unix,  can be down loaded from https://www.virtualbox.org/ (plus installation help, should you need it), it is also available for Unix through your package manager.
 
 
'''Note''' that for Unix, you will need to have the development package and the kernel source or header files installed.
 
 
Install VirtualBox for your operating system, then start it. You will first need to create a virtual machine to install ReactOS into; this is done by clicking on the blue '''New''' button. In the first setup window you will need to give it a name in '''Name:''', then set it to '''Microsoft Windows''' in '''Type:''' and then set it to, either '''WindowsXP(32bit)''' or '''Windows 2003(32 bit)''' in '''Version:''', then for a simple setup, you can accept all the defaults in all the other setup windows (I alter just one item, I select '''VHD (Virtual Hard Disk)''' in the last setup window). There is no need to install ReactOS into the virtual machine just yet, if you want to log the debug output from the start of an installation.
 
 
'''Note:''' You may find it helpful if you name the virtual machine with a descriptive name, such as '''0.4.7-dev-582-g74cc915''' or  '''ReactOS-g74cc915''' or '''ROS-0.4.6''', especially if you intend doing some serious debugging and having several virtual machines with different versions of ReactOS installed.
 
 
There is another user's wiki here [[User:Matthiasbasler#Tutorial:_Getting_a_stable_software_stack_with_ReactOS_on_VirtualBox.]] which covers a more detailed setup for VirtualBox.
 
 
====Windows - com0com====
 
 
Get the latest '''com0com''' from https://sourceforge.net/projects/com0com/files/com0com/ and install it. Then run setup <sup>[<span style="color:#b60000">'''8a'''</span>]</sup>, click on the '''Add Pair''' button, which creates a pair of virtual ports, then click on the '''Apply''' button. There is no need to tick any of the tick boxes.
 
 
In the setup window you will see '''CNCA0''' and '''CNCB0''' which are the newly created virtual ports <sup>[<span style="color:#b60000">'''8'''</span>]</sup> (If you should ever have the need to add more virtual ports, then the next pair will be '''CNCA1''' and '''CNCB1'''). The '''CNCA0'''  is used in the '''<u>P</u>ath/Address:''' in VirtualBox virtual machine serial configuration <sup>[<span style="color:#b60000">'''10'''</span>]</sup> in this format '''\\.\CNCA0''' and the '''CNCB0''' is used in the '''Serial line''' in the Putty serial configuration <sup>[<span style="color:#b60000">'''11a'''</span>]</sup> just as it is.
 
 
The com0com virtual ports process remains until you use the '''Remove''' button in the setup app, to remove them.
 
 
====Unix - tty0tty====
 
 
You can get '''tty0tty''' from https://sourceforge.net/projects/tty0tty/files/ (the latest is currently tty0tty-1.2).
 
 
Unpack the package '''tty0tty-1.2tgz''' to a folder; my OS was able to unpack it to '''/tty0tty-1.2/''', just by clicking on the package.
 
 
It requires compiling, so navigate to the directory '''/tty0tty-1.2/pts''' (cd /tty0tty-1.2/pts) and open a terminal window (right click - '''Window''' - '''Terminal here'''). At the command prompt type '''make''' and shortly you should have an executable file in the '''pts''' folder.
 
Then still within the '''pts''' folder/directory, type '''./tty0tty''' at the command prompt to run <sup>[<span style="color:#b60000">'''8b'''</span>]</sup>. The output could be
 
 
'''(/dev/pts/1) <=> (/dev/pts/2)'''
 
 
or
 
 
'''(/dev/pts/2) <=> (/dev/pts/3)'''
 
 
it may vary. But whatever the left side is, such as '''/dev/pts/2''' will be entered into the '''<u>P</u>ath/Address:''' in the VirtualBox virtual machine's serial configuration <sup>[<span style="color:#b60000">'''10'''</span>]</sup> and whatever the right side is, such as '''/dev/pts/3''' will be entered into the '''Serial line''' in the Putty Serial configuration, instead of the default com or tty <sup>[<span style="color:#b60000">'''11b'''</span>]</sup>.
 
 
I end the tty0tty virtual ports process, by using the '''Ctrl''' - '''c''' combination, but I would expect it to terminate when the terminal window is closed.
 
 
There is another folder in the directory /tty0tty-1.2/module which also requires compiling. This will, when run, create several pairs of virtual ports, which remain until the OS is re-installed or upgraded. I have not used it or included it within this tutorial.
 
 
====Testing com0com and tty0tty====
 
 
To test if it works, configure one instance of putty with '''CNCA0''' in Windows or '''/dev/pts/2''' in Unix and another instance of putty with '''CNCB0''' in Windows or '''/dev/pts/3''' in Unix, then run both Windows Puttys or both Unix Puttys and type into each terminal window. If the input from each terminal window is shown in the other terminal window (what is typed into Putty No1 should display in Putty No2, also what is typed into Putty No2 should be displayed in Putty No1), then you have a working virtual null modem cable.
 
 
Now you can run your VirtualBox virtual machine and install ReactOS.
 
 
'''Note:''' When you run your virtual machine with an installed OS, then make sure that there is no bootable media in any of your external drives (floppy, USB or CD/DVD), else the VirtualBox virtual machine will boot it instead of the installed OS.
 
 
Now you can refer back to [[#The_ReactOS_debugger]]
 
 
====Screenshots====
 
 
<gallery widths="451px" heights="391px" paddings="0px">
 
File:Setup_for_com0com.png|[<span style="color:#b60000">8a</span>] Setup window for com0com.
 
File:tty0tty.png|[<span style="color:#b60000">8b</span>] ‎Starting tty0tty.
 
</gallery>
 
 
 
<gallery widths="759px" heights="588px" paddings="0px"> .
 
File:VirtualBox_Manager.png|[<span style="color:#b60000">9</span>] This is the main window in VirtualBox. It looks the same in both Unix and Windows. Use the '''New''' button to create a new virtual machine, the '''Settings''' button to add or alter settings (select the virtual machine first) and the '''Start''' button starts the selected virtual machine.
 
</gallery>
 
 
<gallery widths="654px" heights="429px" paddings="0px">
 
File:VirtualBox-Settings.png|[<span style="color:#b60000">10</span>] This is the Serial port settings window in VirtualBox. In the '''<u>P</u>ath/Address:''' it is '''\\.\CNCA0''' for '''com0com''' in Windows and '''/dev/pts/2''' for '''tty0tty''' in Unix. Depending on the version of VirtualBox, where you see '''<u>P</u>ath/Address:''' you could see '''Port/File Path:''' instead.
 
</gallery>
 
 
<gallery widths="476px" heights="435px" paddings="0px">
 
File:PuTTY_Configuration.png|[<span style="color:#b60000">11a</span>] Windows '''com0com''' Putty Serial configuration.
 
File:Putty-tty0tty.png|[<span style="color:#b60000">11b</span>] Unix '''tty0tty''' Putty Serial configuration.
 
</gallery>
 
 
 
<p style="font-size:150%;border-top:3px solid #b60000;"></p>
 
 
 
<h2>A layman's guide - <span style="font-size:150%;color:#006000;">How to create a JIRA Issue for your bug.</span></h2>
 
 
 
From the ReactOS.org front page, go to the JIRA page (https://jira.reactos.org/secure/Dashboard.jspa) by clicking on the '''JIRA''' link at the top of the page. If you successfully followed the link you should now be at the Dashboard page of ReactOS JIRA, on the right side of the page <sup><span style="color:#006000">['''1''']</span></sup>, you should see a login form (there is also a login link in the top right of the page, which will open another page with a log in form), just use your forum username and password.
 
 
<gallery widths="655px" heights="400px" paddings="0px">
 
JIRA-Dashboard_login.png|<span style="color:#006000">['''1''']</span> Where to log into JIRA.
 
</gallery>
 
 
<div style="border:1px solid #dd0000;padding:5px">'''Note:''' If you have only just created an account for the forum, you may find that you cannot log into JIRA, if that as happened to you, you will have to wait a few hours and try again (it takes time for your login details (user name, password) to get to all the places it is needed). If at any time you find that you cannot log in, there is something else that you could try; go to the ReactOS.org front page and log out, then log in, go back to the Dashboard page of ReactOS JIRA; now try logging in again.</div>
 
 
When you have logged in, the next thing to do, is a search to see if your bug issue has been reported already. Use the '''Search''' box at the far right of the navigation bar at the top of the page <sup><span style="color:#006000">['''1''']</span></sup> or on the '''Issues''' link on the navigation bar <span style="color:#006000"><sup>['''2''']</sup></span>.
 
<gallery widths="286px" heights="192px" paddings="0px">
 
File:JIRA-search.png|<span style="color:#006000">['''2''']</span> Search for issues.
 
</gallery>
 
Click the '''Search for issues''', which will take you to the '''Search''' <span style="color:#006000"><sup>['''3''']</sup></span> window.
 
<gallery widths="1075" heights="500" paddings="0px">
 
File:SearchPage.png|<span style="color:#006000">['''3''']</span> Search window.
 
</gallery>
 
You need to put your search word(s) in the box '''Contains text''' and press Enter on your keyboard. The list in the side window will update and the first result will be highlighted and the report will be shown in the main window. You can scroll down the list in the side window, by using the down arrow key on your keyboard; the main window will then update with the report which is highlighted in the side window. If you think a reported issue matches the bug issue you wish to report, then, if you think that you can add further information which could be helpful, then use the '''Comment''' button <span style="color:#006000"><sup>['''10''']</sup></span> at the bottom of all the '''Comments''', which opens the '''Comment''' editor <span style="color:#006000"><sup>['''11''']</sup></span>. When you have made your comment, click on the '''Add''' at the bottom right of the editor window.
 
 
If you did not find anything that could be the same bug as yours, then you will have to create your own bug Issue report.
 
<gallery widths="643px" heights="113px" paddings="0px">
 
Jira-Create-Issue-button.png|<span style="color:#006000">['''4''']</span> Select '''Create Issue''' which will open the '''Create Issue''' form.
 
</gallery>
 
 
Don't be intimidated by JIRA, it is very simple to create an issue! You will need to be logged into JIRA and you will see a nice blue '''Create Issue''' button to click, at the top of the page on the navigation bar <sup><span style="color:#006000">['''4''']</span></sup>, which will open a '''Create Issue''' form <sup><span style="color:#006000">['''5''']</span></sup>, when the form appears, there are just 2 input boxes to fill in (leave the others alone).
 
 
<gallery widths="813px" heights="705px" paddings="0px">
 
File:Jira-Create-Issue-Form.png|<span style="color:#006000">['''5''']</span> The '''Create Issue''' form. Fill in the input boxes which I have coloured yellow.
 
</gallery>
 
 
Give a short description of the problem in '''Summary''' (this will be the title of the report).
 
 
In '''Description''', state if you were testing in real hardware (list your computer specification), or in a virtual machine (state what VM you use), then the revision number of ReactOS that you are using (if the problem involves additional software, then include the down-load link to that software), then describe what happens and how to replicate the problem. Here https://jira.reactos.org/browse/CORE-12843 is a good report to give you some ideas on how to make a helpful report, which will help the developers find and fix the problem.
 
 
If you get a debug log or take a photo or video, use the '''Browse''' link in '''Attachment''' or drag and drop files into the '''Attachment''' to upload it.
 
 
That is all you need to fill in, leave the rest to the developers. To submit your report, click on the '''Create''' button in the bottom right of the form.
 
 
 
=== Adding more debug logs, photos and videos. ===
 
Having created a JIRA Issue for your bug, you have a need to add another debug log, photo or video.
 
<gallery widths="660px" heights="65px" paddings="0px">
 
File:JIRA-Issue-button.png |<span style="color:#006000">['''6''']</span> Issues button.
 
</gallery>
 
 
Go to ReatOS JIRA and log in. Then go to the '''Issues''' <sup><span style="color:#006000">['''6''']</span></sup> button and select '''Reported by Me''' <sup><span style="color:#006000">['''7''']</span></sup> and your Issues will be shown.
 
 
<gallery widths="379px" heights="431px" paddings="0px">
 
File:JIRA-add-alter-Issue-No2.png|<span style="color:#006000">['''7''']</span> Then click on the '''Reported by Me''' link, which will take you to a page dedicated to your Issues <span style="color:#006000"><sup>['''8''']</sup></span>.
 
</gallery>
 
<gallery widths="973px" heights="393px" paddings="0px">
 
File:JIRA reported-by-me page.png |<span style="color:#006000">['''8''']</span> '''Reported by me''' Issues window.
 
</gallery>
 
Find your report and then scroll down the side window and select the Issue you want to add more files to. Then use either the '''More''' tab, then in the drop down list, click the '''Attach files''' link <sup><span style="color:#006000">['''9''']</span></sup>.
 
<gallery widths="494px" heights="410px" paddings="0px">
 
File:ADDfiles reported by me.png |<span style="color:#006000">['''9''']</span> Add files.
 
</gallery>
 
 
Or further down at '''Attachments''', you can use the '''Browse''' link or drag and drop files into '''Attachments''' to upload it <sup><span style="color:#006000">['''9''']</span></sup>. In the '''Comment''' box you can describe the attached file(s) and any further information about the Issue you wish to add, then use the '''Attach''' button at the bottom of the form, to attach it all to the report.
 
 
<gallery widths="350px" heights="154px" paddings="0px">
 
File:JIRA-add-comment.png ‎|<span style="color:#006000">['''10''']</span> Below the last comment, you will find the '''Comment''' button.
 
</gallery>
 
 
If you only want to add more information, or to reply to a question from a developer, use the '''Comment''' button <sup><span style="color:#006000">['''10''']</span></sup> at the bottom left of the page, which will open a '''Comment''' form. When you have finished writing in the '''Comment''' form, use the '''Add''' buttom <sup><span style="color:#006000">['''11''']</span></sup> to attach it to the report.
 
 
<gallery widths="677px" heights="295px" paddings="0px">
 
File:JIRA-add-comment-form.png ‎|<span style="color:#006000">['''11''']</span> This is the comment form.
 
</gallery>
 
 
<gallery widths="689px" heights="71px" paddings="0px">
 
File:JIRA-alter-Issue-Description.png ‎|<span style="color:#006000">['''12''']</span> Where to edit your Issue heading.
 
</gallery>
 
When you first created your bug issue report, you may have chosen the wrong words for the '''Summary''' (the summary becomes the title of the report) and you now want to change them for some that better describe your bug. In the '''Reported by me''' Issues window <span style="color:#006000"><sup>['''8''']</sup></span>, move your mouse pointer over the title and a pencil will appear at the end <span style="color:#006000"><sup>['''12''']</sup></span>, click on it and a cursor will appear in the title, so that you can edit the it. , When you have finished editing the title, press Enter on your keyboard.
 
 
<div style="border:2px solid #dd0000;padding:5px"><span style="font-size:150%;color:#dd0000">*</span>
 
You are strongly advised to follow the instructions here in the main text and not to go altering things like '''Priority''', '''Component/s''' or '''Fixed Version/s''', which are accessible from the '''Edit''' button <span style="color:#006000">['''9''']</span>. Please do not upset the developers by altering things that you do not fully understand! You may think that a bug is a '''Blocker''' or '''Critical''', but the developers may think that it is only '''Minor''' or '''Trivial'''.</div>
 
 
 
<gallery widths="640px" heights="306px" paddings="0px">
 
File:Direct-comment-at-JIRA-Dashboard.png |<span style="color:#006000">['''13''']</span> Make a comment direct from the JIRA Dashboard.
 
</gallery>
 
If you read JIRA Dashboard commits, and see something that you can usefully comment on, then you can make a comment by clicking on '''Comment''' at the bottom of the commit, which will open a drop down form <sup><span style="color:#006000">['''13''']</span></sup>, where you can make your comments. When you have finished, just click on the '''Add''' button.
 
 
<div style="border:1px solid #dd0000;padding:5px">'''Note:''' When adding comments to your own or other peoples reports, ask yourself ''''does this add value to the report'''', ''''is it going to be helpful''''. Please do not make trivial or silly comments, it is better to click '''Cancel''' than to fill JIRA with rubbish comments. So make sure that what you have typed will help others, before you activate the '''Add''' button.</div>
 
 
 
 
<gallery widths="230px" heights="283px" paddings="0px">
 
File:|<sup><span style="color:#006000">['''10''']</span></sup>
 
</gallery>
 
 
 
<p style="font-size:150%;border-top:3px solid #006000;"></p>
 
 
 
<h2>A layman's guide - <span style="font-size:150%;color:#804000;">Regression testing: finding the guilty revision.</span></h2>
 
 
 
The ISO files now come in the file format shown below.
 
<pre style="background:white;border:none;">
 
reactos-bootcd-0.4.7-dev-571-gc22817d-x86-gcc-lin-dbg.7z
 
reactos-bootcd-0.4.7-dev-571-gc22817d-x86-msvc-win-dbg.7z
 
                              c22817d
 
</pre>
 
To do a search at the '''getbuilds''' page (https://www.reactos.org/getbuilds/) you only need the portion shown in the last line (above).
 
 
Because of the way that Git tracks commits to the source tree, you can no longer use numbers in the same way that you could with SVN. So if you have tried a revision some days ago that was good and did not have the problem, then you can get the reference code (as shown above) from this '''good''' revision, then the reference code from the '''bad''' revision that exhibits the problem. Using these two numbers, you can then do a search at the '''getbuilds''' page (https://www.reactos.org/getbuilds/).
 
 
To do a search, just uncheck all the boxes that are not required, put the two codes in the input box, with a dash between them, like so: '''48fe086-74cc915''', then click the search button.  The search will then list all the revisions between and including the ones typed into the search input box.
 
 
 
You are advised to copy paste the search results into a Text Editor, for further reference, unless you keep the page open with search result in.
 
 
If you know that you have tested a good revision in the past, but cannot remember it's revision number, then you can list all the bootcd files at https://iso.reactos.org/bootcd/.
 
 
We will assume that revision '''74cc915''' has a regression, so it is the ' '''bad''' ' revision, you will need to find a ' '''good''' ' revision.
 
 
Using revision '''74cc915''' as the '''bad reference point''', using the list of ISO files, go back in increments of 100 or one week, installing and testing them, until you find the ' '''good''' ' revision. When you have found a ' '''good''' ' revision, that will be the '''good reference point''' and the last ' '''bad''' ' revision will become the new '''bad reference point'''. Now you have two reference points, a known ' '''bad''' ' revision and a known ' '''good''' ' revision.
 
 
The guilty revision must be somewhere in between the two reference (revision) points!
 
 
Next choose a revision that is half way between the two revisions, then test that revision to see if it is good, it will then become the new '''good reference point''', but if it is bad, it will then become the new '''bad reference point'''. Keep choosing a revision that is half way between the two, until you have found where the revision changes from good to bad; the bad is the guilty revision that regressed!
 
 
Remember that the guilty revision is always between the last ' '''good''' ' revision and the last ' '''bad''' ' revision, until you have reached the point where they are next to each other.
 
 
The old SVN ISO files are in this format '''r75098''' and are still available from https://iso.reactos.org/bootcd/, but are not now available at the '''getbuilds''' page (https://www.reactos.org/getbuilds/), because they are no longer being created.
 
 
'''Note''' that the old revision numbers cannot be used in the search input box at the '''getbuilds''' page.
 
 
It as been brought to my attention, that Git has some built in functions that do the same as in this guide. So if you have a local source tree, then you may like to read this '''https://git-scm.com/docs/git-bisect'''. '''Warning''': only use these git functions on your local source tree, because of what they do to the tree!
 
 
<p style="font-size:150%;border-top:3px solid #804000;"></p>
 
 
 
<h2>A layman's guide - <span style="font-size:150%;color:#006080;">log2lines.</span></h2>
 
 
In this tutorial there is also a Unix based subsection.
 
 
You have created a Jira Issue for a bug, you are then asked to translate the addresses in the backtrace that are in the debug log.
 
 
To do this you will need '''log2lines''', which comes with  '''RosBE''', if you haven't already got '''RosBE''', then it can be down-loaded from Sourceforge http://sourceforge.net/projects/reactos/files/
 
 
Before you down-load RosBE, create some folders on whatever drive you like and call them whatever you like. In my example, I have created a master folder on drive '''D:''', which I have called '''DebugWork''', this will contain all the files and folders.
 
 
You will also need to have 7zip installed http://www.7-zip.org/download.html; Peazip will not work.
 
 
Example:
 
 
'''D:\DebugWork'''            (this is the master folder, all the other folders and files are stored in this).
 
 
'''D:\DebugWork\RosBE'''      (install RosBE into this folder, but if you already have RosBE elsewhere, you will not need this).
 
 
Put the debug log and the iso into the folder '''D:\DebugWork''' (in my example they are '''explorer-0.4.7-dev-557-g57cda5a.log''' and '''reactos-bootcd-0.4.7-dev-557-g57cda5a-x86-gcc-lin-dbg.iso''').
 
 
Using the example from above, you would type this at the RosBE command prompt:
 
 
<span style="color:#006080;">'''D:\DebugWork\RosBE></span>log2lines -m -d D:\DebugWork\reactos-bootcd-0.4.7-dev-557-g57cda5a-x86-gcc-lin-dbg.iso <D:\DebugWork\explorer-0.4.7-dev-557-g57cda5a.log> D:\DebugWork\explorer-0.4.7-dev-557-g57cda5a-new.log'''
 
 
Explanation:
 
 
<span style="color:#006080;">'''D:\DebugWork\RosBE>'''</span> ................................ The RosBE command prompt (which shows the directory of RosBE).
 
 
'''log2lines -m -d''' ................................................ The command to start log2lines with two optional run-time commands.
 
 
The command '''-m''' puts a '''<big>*</big>''' at the front of the translated line, and the command '''-d''' indicates that it is a directory or iso image.
 
 
'''D:\DebugWork\reactos-bootcd-0.4.7-dev-557-g57cda5a-x86-gcc-lin-dbg.iso''' ....... The iso's directory path and name.
 
 
'''<D:\DebugWork\explorer-0.4.7-dev-557-g57cda5a.log>''' ........ The debug log's directory path and name (you must include '''<''' at the front and '''>''' at the back).
 
 
'''D:\DebugWork\explorer-0.4.7-dev-557-g57cda5a-new.log''' ... The directory where the new translated log will be written, with it's name.
 
 
 
If you have RosBE already installed elsewhere, then, using the same folder and files as in the example above, you would just start RosBE and at the command prompt, type: '''log2lines -m -d D:\DebugWork\reactos-bootcd-0.4.7-dev-557-g57cda5a-x86-gcc-lin-dbg.iso <D:\DebugWork\explorer-0.4.7-dev-557-g57cda5a.log> D:\DebugWork\explorer-0.4.7-dev-557-g57cda5a-new.log'''
 
 
 
 
=== log2lines - Screenshots ===
 
<gallery widths="668px" heights="295px" paddings="0px">
 
File:RosBElog2lines.png|RosBE '''log2lines''' - run as in the above example.
 
</gallery>
 
<gallery widths="660px" heights="439px" paddings="0px">
 
File:RosBE-log2lines.png|RosBE '''log2lines''' - run from my compiling directory with the iso and debug log in the directory '''DebugWork'''.
 
</gallery>
 
<gallery widths="242px" heights="395px" paddings="0px">
 
File:DebugWork-folder.png|This shows the directory from the above example, after log2lines had been executed.
 
</gallery>
 
<gallery widths="716px" heights="422px" paddings="0px">
 
File:Bt-before.png|This shows the backtrace before log2lines as been run. (ignore the red in the image, it is from the spell checker). Compare this with the one just below. Look for the lines that start with an asterix (<big>*</big>) in the image below, these are the lines that log2lines has added extra information to.
 
</gallery>
 
<gallery widths="730px" heights="421px" paddings="0px">
 
File:Bt-after.png|This shows the backtrace after log2lines as been run. (ignore the red in the image, it is from the spell checker)
 
</gallery>
 
 
 
===<span style="color:#006080">log2lines - '''Unix subsection'''</span>===
 
 
To be able to use '''log2lines''' in the Unix version of RosBE, you will have to compile the source code first, then you will find '''log2lines''' in the '''/reactos/host-tools/''' folder. To use my example, it will be in '''/home/RosBuild/compiled/reactos/host-tools/'''.
 
 
See the '''Layman's guide - How to compile ReactOS - Unix subsection''', for instructions on how to install RosBE-Unix.
 
 
The log2lines command is in this format: '''log2lines options ISO <old log> new log'''
 
 
Explanation:
 
 
'''log2lines''' ........ Executes log2lines.
 
 
'''options''' .......... Optional run-time commands for log2lines. '''-m''' Marks the translated line with an <span style="font-size:110%>'''*'''</span> and '''-d''' is for directory.
 
 
'''ISO''' .................. This is the name and location of the ISO image that you used.
 
 
'''<old log>''' ........ This is the location and name of the original debug log.
 
 
'''new log''' .......... This is the location and name for the modified debug log. It will be written with that name and at that location.
 
 
<small>See also the explanation in the main section above.</small>
 
 
For the following example, there will be two extra folders in the '''/home/RosBuild''' directory, one called '''debug-logs''', where the debug logs are kept and the other called '''ISO-images''', where the ISO image files are kept. The debug log that will be run through log2lines, is called '''SteamError2.log'''.
 
 
Example:
 
 
Start RosBE and at the command prompt, type:
 
 
'''/home/RosBuild/compiled/reactos/host-tools/log2lines -m -d /home/RosBuild/ISO-images/bootcd-75458-dbg.iso </home/RosBuild/debug-logs/SteamError2.log> /home/RosBuild/debug-logs/SteamError2-new.log'''
 
 
'''NOTE:'''
 
For log2lines to work, you must give the full path to the host-tools directory.
 
If you get any error message, for example '''log2lines: command not found''', then check that your paths are all correct.
 
 
 
<p style="font-size:150%;border-top:3px solid #006080;"></p>
 
 
<h2>A layman's guide - <span style="font-size:150%;color:#a00050;">Miscellaneous.</span></h2>
 
====Scripts====
 
In this section you will find some useful scripts, which help you to achieve things already decribed in the sections above.
 
 
Use the following scripts at your own discretion. As with other software, the scripts come with no guarantee!
 
=====<big>Windows</big> - Create the Tutorial working environment=====
 
This script is intended to be used once, to automate (but needs user input) the setting up of a working environment (all the directories, software and ReactOS source code) as described in the Layman's guides. But could also be a useful peice of software to test in ReactOS.
 
 
'''What will this script do?'''
 
 
It first ask the user for a drive letter, then it will use that drive letter to create the following directory structure:
 
<pre>
 
drive letter:\REACTOS_DEVELOPMENT
 
              +---Compiled
 
              +---Debug
 
              +---ISO
 
              +---Required_Software
 
              +---RosBE
 
              +---Source
 
</pre>
 
It then down loads a none zipped, none installable version of '''wget''', then down loads '''7-zip''', '''curl''', '''Git''' for Windows and '''RosBE'''. All these software down loads must be saved into the '''Required_Software''' directory. After each down load, it will start the software's installer, as required.
 
 
 
Next it will down load and clone '''<nowiki>https://github.com/reactos/reactos.git</nowiki>''' into the '''source''' directory, then it creates a script '''Revision.txt''', which stores the date and revision number. Then it creates another script '''update-source.cmd''', which can be used to update the local source tree, when required (it will update '''Revision.txt''' and also create/update '''update.txt''' with commit history). It also creates a script ('''iso-revisioner.cmd''') to move an iso from the '''Compiled''' directory to the '''ISO''' directory and add the revision number to  it, so bootcd.iso will become something like '''0.4.9-dev-652-gdffd748 (updated at 19:01:18.70 on 08/04/2018)'''. These scripts will be found in the '''REACTOS_DEVELOPMENT''' directory.
 
 
'''Note:''' The drive letter that was selected in the running script, will also be in the scripts '''update-source.cmd''' and '''iso-revisioner.cmd'''!
 
 
This is the script (below), which has intentionally been reduced in size to fit the page!
 
<code style="font-size:50%;"><pre>
 
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
::      This script automates the setting up of a working environment, as per the Layman's guides.    ::
 
:: I hate EULAs.  ©Nobody.  Use at your own risk! It worked for me and did what it was intended to do. ::
 
::      It is not the most elegant script and it maybe is over-kill in parts, but it works for me.    ::
 
::                                            Version 0.3                                            ::
 
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
@echo off
 
:: Populate the variable, ready for use.
 
set text= * An error occured down loading
 
:: RosBE revision number. Change it here and it will be applied throughout the script.
 
set RBEver=2.1.6
 
:: Put the URLs into variables, this will save line length later. Some links may need to be changed in the future.
 
set Wget=https://eternallybored.org/misc/wget/1.19.4/32/wget.exe
 
set zip=http://www.7-zip.org/a/7z1604.exe
 
set Curl=https://winampplugins.co.uk/curl/curl_7_53_1_openssl_nghttp2_x86.7z
 
set GetGit=https://github.com/git-for-windows/git/releases/download/v2.10.0.windows.1/Git-2.10.0-32-bit.exe
 
set RBE=https://sourceforge.net/projects/reactos/files/RosBE-Windows/i386/%RBEver%/RosBE-%RBEver%.exe/download
 
:: Put the paths into variables.
 
set pf=C:\"Program Files"
 
set R_D=:\ReactOS_Development
 
set R_Dcmp=:\ReactOS_Development\Compiled
 
set R_Ddbg=:\ReactOS_Development\Debug
 
set R_Diso=:\ReactOS_Development\ISO
 
set R_Dreqs=:\ReactOS_Development\Required_Software
 
set R_Drbe=:\ReactOS_Development\RosBE
 
set R_Dscrpt=:\ReactOS_Development\Scripts
 
set R_Dsrc=:\ReactOS_Development\Source
 
::
 
cls
 
echo  ##############################################################################
 
echo  # This script will setup a working environment similar to what is described  #
 
echo  # in the Layman's guides at https://reactos.org/wiki (Windows XP or ReactOS) #
 
echo  #  Should only need to be run once, but can safely be run several times.    #
 
echo  ##############################################################################
 
echo  Now starting the setup!
 
:choice
 
echo  Choose which drive to create the directory tree in!
 
echo  Such as C, D, E, F, etc.
 
set /p drv= Enter drive letter
 
:: Now check to see if the selected drive exists!
 
if not exist %drv%:\ (echo  * Drive %drv%: does not exist! && goto :choice)
 
echo  The directory tree will now be created in drive %drv%:
 
:: Now make the directory tree. If the directory does not exist, then create it.
 
if not exist %drv%%R_D%  (mkdir %drv%%R_D% && echo  * Created %drv%%R_D%)
 
if not exist %drv%%R_Dcmp%  (mkdir %drv%%R_Dcmp% && echo  * Created \Compiled)
 
if not exist %drv%%R_Ddbg%  (mkdir %drv%%R_Ddbg% && echo  * Created \Debug)
 
if not exist %drv%%R_Diso%  (mkdir %drv%%R_Diso% && echo  * Created \ISO)
 
if not exist %drv%%R_Dreqs%  (mkdir %drv%%R_Dreqs% && echo  * Created \Required_Software)
 
if not exist %drv%%R_Drbe%  (mkdir %drv%%R_Drbe% && echo  * Created \RosBE)
 
if not exist %drv%%R_Dscrpt%  (mkdir %drv%%R_Dscrpt% && echo  * Created \Scripts)
 
if not exist %drv%%R_Dsrc%  (mkdir %drv%%R_Dsrc% && echo  * Created \Source)
 
:: Move into the software directory to down load the required software.
 
cd %drv%%R_Dreqs%
 
echo  ################## PLEASE READ THE FOLLOWING ##################
 
echo  wget will be down loaded next, either with dwnl (ReactOS app)
 
echo  or with your default browser!
 
echo  Please make sure that your browser saves it to
 
echo                  %drv%%R_Dreqs%.
 
:: Pause here to give time for the above text to be read.
 
set /p temp="Please note the above and when you are ready, press Enter to continue"
 
:getwget
 
if not exist wget.exe (echo  ... Down loading wget! && dwnl %Wget% wget.exe || echo Your browser will now open! && start %Wget% || goto :errorwget) else (echo  * You already have wget.exe && goto :get7-zip)
 
set /p temp="When wget has been saved to %R_Dreqs%, press Enter to continue"
 
:get7-zip
 
if exist %pf%\7-Zip\7z.exe (echo  * You have 7zip installed && goto :getcurl)
 
if not exist 7z1604.exe (dwnl %zip% 7z1604.exe || wget %zip% > 7z1604.exe || goto :error7-zip)
 
set /p temp="When 7zip has been saved to %R_Dreqs%, press Enter to continue"
 
if exist 7z1604.exe (echo  * 7zip has been successfully down loaded! && goto :inst7-zip)
 
:inst7-zip
 
if not exist %pf%\7-Zip\7z.exe (echo  ... Running 7-zip installer && start 7z1604.exe && ping -n 11 127.0.0.1>nul)
 
if exist %pf%\7-Zip\7z.exe (echo  * 7-zip is now installed! && goto :getcurl)
 
:getcurl
 
if exist curl.exe (echo  * You already have curl && goto :getgit)
 
if not exist curl_7_53_1_openssl_nghttp2_x86.7z (echo  ... Down loading curl. && wget --no-check-certificate %Curl% || goto :errorcurl)
 
set /p temp="When curl has been saved to %R_Dreqs%, press Enter to continue"
 
if exist curl_7_53_1_openssl_nghttp2_x86.7z (echo  * curl has been successfully down loaded! && goto :extractcurl)
 
:extractcurl
 
if exist curl_7_53_1_openssl_nghttp2_x86.7z (start %pf%\7-Zip\7z.exe e curl_7_53_1_openssl_nghttp2_x86.7z && ping -n 11 127.0.0.1>nul)
 
if exist curl.exe (echo  * curl is now ready to use!)
 
:getgit
 
if not exist %pf%\Git\bin\git.exe (echo  ... Down loading Git && curl --cookie nada --location %GetGit% > Git-2.10.0-32-bit.exe || goto :errorgit) else (echo  * git is already installed! && goto :getRosBE)
 
set /p temp="When git has been saved to %R_Dreqs%, press Enter to continue"
 
if exist Git-2.10.0-32-bit.exe (echo  * Git has been successfully down loaded! && goto :instgit)
 
:instgit
 
echo  #################### PLEASE READ THE FOLLOWING ####################
 
echo ** DO NOT select * mintty * in the installation.
 
echo  Please select * Windows' default consel window * in the installation.
 
set /p temp="Please note the above and when you are ready, press Enter to continue"
 
if exist Git-2.10.0-32-bit.exe (echo  ... Starting the Git installer. && start Git-2.10.0-32-bit.exe || echo  * Failed to install git!)
 
set /p temp="When git has been installed, press Enter to continue"
 
if exist %pf%\Git\bin\git.exe (echo  *  git has been successfully installed)
 
:getRosBE
 
if not exist RosBE-%RBEver%.exe (echo  * Down loading RosBE && curl --cookie nada --location %RBE% > RosBE-%RBEver%.exe || goto :errorRosBE) else (echo  * Found RosBE-%RBEver% installer, so it should be installed! && goto :clone)
 
set /p temp="When RosBE has been saved to %R_Dreqs%, press Enter to continue"
 
if exist RosBE-%RBEver%.exe (echo  * RosBE has been successfully down loaded!)
 
:instRosBE
 
echo  #################### PLEASE READ THE FOLLOWING ####################
 
echo  The RosBE installer will give you the choice where to install it to.
 
echo  You can install it to it's default directory or here in
 
echo  %drv%%R_Drbe% or where ever you choose.
 
:: Pause here to give time for the above text to be read.
 
set /p temp="Please note the above and when you are ready, press Enter to continue"
 
if exist RosBE-%RBEver%.exe (start RosBE-%RBEver%.exe || echo  * Failed to install RosBE!)
 
set /p temp="When RosBE has been installed, press Enter to continue"
 
:clone
 
if exist %drv%%R_Dsrc%\reactos echo  * The source appears to have already been cloned && goto :make_script
 
cd %drv%%R_Dsrc%
 
echo  ... Cloning the ReactOS source tree to a local folder. && git clone https://github.com/reactos/reactos.git || goto :giterror
 
set /p temp="When the source tree has been cloned, press Enter to continue"
 
cd %drv%%R_Dsrc%\reactos
 
echo ~~~~~ %time% - %date% ~~~~~ 1>>  %drv%%R_Dscrpt%\Revision.txt
 
:: Find the revision number and write it to revision.txt.
 
git describe 1>> %drv%%R_Dscrpt%\Revision.txt
 
:make_script
 
:: Check here to see if the script 'update-source.cmd' has already been created.
 
if exist %drv%%R_Dscrpt%\update-source.cmd (goto :finish)
 
:: Start making the script
 
echo  * Creating the script update-source.cmd
 
echo :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 1>> %drv%%R_Dscrpt%\update-source.cmd
 
echo :: Automates the updating of your local source tree as per the tutorial.                          :: 1>> %drv%%R_Dscrpt%\update-source.cmd
 
echo :: I hate EULAs.  ©Nobody. Use at your own risk! It worked for me and did what I wanted it to do. :: 1>> %drv%%R_Dscrpt%\update-source.cmd
 
echo :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 1>> %drv%%R_Dscrpt%\update-source.cmd
 
echo @echo off 1>> %drv%%R_Dscrpt%\update-source.cmd
 
echo cls 1>> %drv%%R_Dscrpt%\update-source.cmd
 
echo echo  * Checking for source code changes and additions! Please give it time to complete. 1>> %drv%%R_Dscrpt%\update-source.cmd
 
echo cd %drv%%R_Dsrc%\reactos 1>> %drv%%R_Dscrpt%\update-source.cmd
 
echo git  pull origin 1^>^> %drv%%R_Dscrpt%\update.txt 1>> %drv%%R_Dscrpt%\update-source.cmd
 
echo :: Find the revision number and write it to Revision.txt. 1>> %drv%%R_Dscrpt%\update-source.cmd
 
echo for /F "tokens=* usebackq" %%%%v in ^(`git describe`^) do ^(set version=%%%%v^) 1>> %drv%%R_Dscrpt%\update-source.cmd
 
echo echo #################### %%version%% updated at %%time%% on %%date%% #################### 1^>^> %drv%%R_Dscrpt%\update.txt 1>> %drv%%R_Dscrpt%\update-source.cmd
 
echo echo * %%version%% ^(updated at %%time%% on %%date%%^) 1^>^> %drv%%R_Dscrpt%\Revision.txt 1>> %drv%%R_Dscrpt%\update-source.cmd
 
echo echo            ~~~~~~~~~~~~~~ Finished. ~~~~~~~~~~~~~~ 1>> %drv%%R_Dscrpt%\update-source.cmd
 
::
 
:: Make a script to add the revision number to the iso in the Compiled directory and move it to the ISO directory
 
::
 
echo  * Creating the script iso-revisioner.cmd
 
echo @echo off 1>> %drv%%R_Dscrpt%\iso-revisioner.cmd
 
echo cls 1>> %drv%%R_Dscrpt%\iso-revisioner.cmd
 
echo :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 1>> %drv%%R_Dscrpt%\iso-revisioner.cmd
 
echo ::  This script moves a locally compiled iso, from Compiled directory  :: 1>> %drv%%R_Dscrpt%\iso-revisioner.cmd
 
echo ::          to the ISO directory, adding the revision number.          :: 1>> %drv%%R_Dscrpt%\iso-revisioner.cmd
 
echo ::      I hate EULAs.  Copyright  Nobody. Use at your own risk!        :: 1>> %drv%%R_Dscrpt%\iso-revisioner.cmd
 
echo ::          It worked for me and did what I wanted it to do.          :: 1>> %drv%%R_Dscrpt%\iso-revisioner.cmd
 
echo :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 1>> %drv%%R_Dscrpt%\iso-revisioner.cmd
 
echo echo Changing directory to %drv%%R_Dsrc%\reactos 1>> %drv%%R_Dscrpt%\iso-revisioner.cmd
 
echo cd %drv%%R_Dsrc%\reactos 1>> %drv%%R_Dscrpt%\iso-revisioner.cmd
 
echo for /F "tokens=* usebackq" %%%%v in ^(`git describe`^) do ^(set version=%%%%v^) 1>> %drv%%R_Dscrpt%\iso-revisioner.cmd
 
echo cd %drv%%R_Dcmp% 1>> %drv%%R_Dscrpt%\iso-revisioner.cmd
 
echo if exist livecd.iso ^( echo found livecd ^&^& move %drv%%R_Dcmp%\livecd.iso %drv%%R_Diso%\%%version%%-livecd.iso ^) 1>> %drv%%R_Dscrpt%\iso-revisioner.cmd
 
echo if exist bootcd.iso ^( echo found bootcd ^&^& move %drv%%R_Dcmp%\bootcd.iso %drv%%R_Diso%\%%version%%-bootcd.iso ^) 1>> %drv%%R_Dscrpt%\iso-revisioner.cmd
 
echo if exist hybrid.iso ^( echo found hybridcd ^&^& move %drv%%R_Dcmp%\hybridcd.iso %drv%%R_Diso%\%%version%%-hybridcd.iso ^) 1>> %drv%%R_Dscrpt%\iso-revisioner.cmd
 
echo echo            ~~~~~~~~~~~~~~ Finished. ~~~~~~~~~~~~~~ 1>> %drv%%R_Dscrpt%\iso-revisioner.cmd
 
::
 
echo  #################### PLEASE READ THE FOLLOWING ####################
 
echo The working environment should now be all setup and ready to use.
 
echo A batch script 'update-source.cmd' has been created in %drv%%R_Dscrpt%.
 
echo Use this script to update the source tree.
 
echo A batch script 'iso-revisioner.cmd' has been created in %drv%%R_Dscrpt%.
 
echo Use this script to move a compiled iso from the Compiled directory
 
echo into the ISO directory and add the revision number to it.
 
:finish
 
echo .
 
echo            ~~~~~~~~~~~~~~ Finished. ~~~~~~~~~~~~~~
 
set /p temp="  Press Enter to exit"
 
exit
 
:errorwget
 
echo  %text% wget. && goto :failed
 
:error7-zip
 
echo  %text%  7-zip. && goto :failed
 
:errorcurl
 
echo  %text%  curl. && goto :failed
 
:errorgit
 
echo  %text%  git. && goto :failed
 
:errorRosBE
 
echo  %text% RosBE. && goto :failed
 
:giterror
 
:: This was added because the system did not find git the first time.
 
echo  * An error occured while trying to clone the ReactOS source tree!
 
echo  ######################### PLEASE READ THE FOLLOWING #########################
 
echo  NOTE: If this script is run again from the begining, it will first check
 
echo  for the needed software, before attempting any more down loads or installs!
 
echo  So you could run the script at a another time to clone the source.
 
set /p yes-no= Do you want to retry to clone the ReactOS source now [y/n]?
 
if %yes-no%==y echo  * Running the clone section again && goto :clone
 
if %yes-no%==n echo * You can still try again later. && goto :failed
 
:failed
 
echo .
 
echo    *********** Unforutatley, the script as failed to complete! ***********
 
set /p temp="  Press Enter to exit"
 
exit
 
</pre></code>
 
To get the script, just copy from here and paste it into a good text editor (not Windows Notepad.exe), then save it with the file extension of '''cmd''' and run it at your leisure. It will save you a lot of typing (if you are happy with the directory names) and only needs to be run once to create a working environment, but can safely be run several times without doing an harm. Before it writes any to your drive, it will check to see if it already exists.
 
 
'''Using the two scripts that it creates:'''
 
 
'''iso-revisioner.cmd'''
 
 
Use this to move a compiled iso, from the '''Compiled''' directory to the '''ISO''' directory; it will add the revision number to the front of the iso, so that '''bootcd.iso''' becomes something like '''0.4.9-dev-652-gdffd748-bootcd.iso'''
 
 
'''update-source.cmd'''
 
 
Use this to update your local source tree, either by double clicking on it (easiest way) or running it from a '''command''' window. It will write to two text files, '''Revision.txt''' which stores the revision number with the time and date, '''update.txt''' which stores all the commit messages for that update, along with the time and date.
 
 
 
This is what the entries that are written to '''Revision.txt''' look like when you use '''update-source.cmd''' to update your local source:
 
<pre>
 
* 0.4.9-dev-652-gdffd748 (updated at 19:01:18.70 on 08/04/2018)
 
* 0.4.9-dev-657-ge195199 (updated at 14:06:56.16 on 09/04/2018)
 
</pre>. 
 
 
And this is an entry in '''update.txt'''
 
<pre>
 
Updating 10e4517..dffd748
 
Fast-forward
 
dll/apisets/api-ms-win-core-fibers-l1-1-0.spec |  8 +-
 
dll/apisets/api-ms-win-core-fibers-l1-1-1.spec |  8 +-
 
dll/apisets/api-ms-win-core-synch-l1-1-0.spec  |  2 +-
 
dll/apisets/api-ms-win-core-synch-l1-2-0.spec  |  2 +-
 
dll/apisets/api-ms-win-core-synch-l1-2-1.spec  |  2 +-
 
dll/apisets/update.py                          |  33 ++++--
 
dll/win32/kernel32/client/fiber.c              | 148 ++++++++++++++++---------
 
dll/win32/kernel32/kernel32.spec              |  8 +-
 
dll/win32/kernel32_vista/k32_vista.h          |  1 +
 
dll/win32/kernel32_vista/kernel32_vista.spec  |  2 +
 
dll/win32/kernel32_vista/sync.c                |  31 +++++-
 
win32ss/user/winsrv/usersrv/harderror.c        |  25 ++---
 
12 files changed, 171 insertions(+), 99 deletions(-)
 
#################### 0.4.9-dev-652-gdffd748 updated at 19:01:18.70 on 08/04/2018 #################### 
 
 
</pre>
 
<gallery widths="1045px" heights="159px">
 
File:Update-source.png
 
</gallery>
 
If you do not want to log the commits, then you will have to open '''update-source.cmd''' in a text editor and remove the text highlight in pale blue, as shown in the above image, which will stop '''update.txt''' from being created and written to.
 
 
 
==UNIX section ==
 
 
 
===Software checker-installer for RosBE===
 
This script will check for any of the required dependancies for the '''R'''eact'''OS''' '''B'''uild '''E'''nvironment (RosBE) and if any are found to be missing, then the script will then look for a Package Manager from a list, if your system's Package Manager is in the list, it will then try to install the missing application.
 
 
It should work in the following Distros:
 
<pre>
 
  Distro:                          Package Manager:      Package type:
 
* Antix 17, a debian derivative            apt                deb
 
* Antix 17, a debian derivative            apt-get            deb
 
* Fedora 28 (Redhat)                      dnf                rpm
 
* gecko, a opensuse derivative            zypper            rpm
 
* Manjaro, a Arch derivative              pacman            pkg.tar.xz
 
* SME, a CentOS/Fedora derivative          yum                rpm
 
* Vector, a slackware derivative          slatp-get          txz
 
</pre>
 
 
It does not work for all distos, because there are lots of different package managers and also some distros put some apps in different packages or name the package differently to other distros.
 
 
This is the script:
 
<pre style="font-size:60%">
 
#!/bin/bash
 
#######################################################################################################
 
#        This script checks for missing application and will install them via sudo privilage .        #
 
#                        I hate EULAs. Copyright Nobody.  Use at your own risk!                      #
 
#                        It worked for me and did what it was intended to do.                        #
 
#######################################################################################################
 
 
clear
 
 
# Text colour
 
bwhit='\033[1;37m' # Bright White
 
pblue='\033[1;4m'  # Pale Blue
 
bred='\033[1;31m'  # Bright Red
 
bgrun='\033[1;32m' # Bright Green
 
byel='\033[1;33m'  # Bright Yellow
 
dyel='\033[0;33m'  # Dark Yellow
 
rs='\033[0m'      # Reset the text back to the default
 
 
mis="MISSING"
 
got="FOUND"
 
 
if [ ! sudo ] # if not installed.
 
then
 
    printf " *  Please install sudo\n"
 
    exit
 
fi
 
 
# OK. This works in Antix, a debian derivative.
 
function apt_install()
 
{
 
helper_apps="as bison curl flex gcc git g++ make makeinfo pkg-config python zlib";
 
cnt=0
 
for have_we in $helper_apps;
 
do
 
  if ! [ -x "$(command -v $have_we)" ]
 
  then
 
    if [ $have_we = "as" ] # 'as' is in package binutils
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n" && sudo apt install binutils || printf " ${bred}*${rs} Failed to install $have_we\n"
 
    elif [ $have_we = "makeinfo" ] # 'makeinfo' is in package texinfo
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n" && sudo apt install texinfo || printf " ${bred}*${rs} Failed to install $have_we\n"
 
    elif [ $have_we = zlib ]
 
    then
 
      if ! pkg-config --exists zlib;
 
      then
 
        printf " ${byel}*${rs} Installing $have_we\n" && sudo apt install zlib1g zlib1g-dev || printf " * Failed to install $have_we\n"
 
      fi
 
    else
 
  printf " ${byel}*${rs} Installing $have_we\n" && sudo apt install $have_we || printf " ${bred}*${rs} Failed to install $have_we\n"
 
    ((cnt++))
 
    fi
 
  else
 
    printf " ${bgrun}*${rs} Searched and found $have_we.\n"
 
  fi
 
done
 
check_for_apps
 
}
 
 
# OK. This works in Antix, a debian derivative.
 
function apt-get_install()
 
{
 
helper_apps="as bison curl flex gcc git g++ make makeinfo pkg-config python zlib";
 
cnt=0
 
for have_we in $helper_apps;
 
do
 
  if ! [ -x "$(command -v $have_we)" ]
 
  then
 
    if [ $have_we = "as" ] # 'as' is in package binutils
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n" && sudo apt-get install binutils || printf " ${bred}*${rs} Failed to install $have_we\n"
 
    elif [ $have_we = "makeinfo" ] # 'makeinfo' is in package texinfo
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n" && sudo apt-get install texinfo || printf " ${bred}*${rs} Failed to install $have_we\n"
 
    elif [ $have_we = zlib ]
 
    then
 
      if ! pkg-config --exists zlib;
 
      then
 
        printf " ${byel}*${rs} Installing $have_we\n" && sudo apt-get install zlib1g zlib1g-dev || printf " * Failed to install $have_we\n"
 
      fi
 
    else
 
  printf " ${byel}*${rs} Installing $have_we\n" && sudo apt-get install $have_we || printf " ${bred}*${rs} Failed to install $have_we\n"
 
    ((cnt++))
 
    fi
 
  else
 
    printf " ${bgrun}*${rs} Searched and found $have_we.\n"
 
  fi
 
done
 
check_for_apps
 
}
 
 
# OK This works in Fedora 28.
 
function dnf_install()
 
{
 
helper_apps="as bison curl flex gcc git g++ make makeinfo pkg-config python zlib";
 
cnt=0
 
for have_we in $helper_apps;
 
do
 
  if ! [ -x "$(command -v $have_we)" ]
 
  then
 
    if [ $have_we = as ] # 'as' is in package binutils
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n"  && sudo dnf install binutils || printf " ${bgrun}*${rs} Failed to install $have_we\n"
 
    elif [ $have_we = makeinfo ] # 'makeinfo' is in package texinfo
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n"  && sudo dnf install texinfo || printf " ${bgrun}*${rs} Failed to install $have_we\n"
 
    elif [ $have_we = g++ ] # 'g++' is in package gcc-c++ possibly for all rpm packages.
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n"  && sudo dnf install gcc-c++ || printf " ${bgrun}*${rs} Failed to install $have_we\n"
 
    elif [ $have_we = zlib ]  # zlib has it's own package but requires zlib-devel for pkg-config to find it.
 
    then
 
      if ! pkg-config --exists zlib;
 
      then
 
        printf " ${byel}*${rs} Installing zlib and zlib-devel\n" && sudo dnf install zlib zlib-devel || printf " ${bgrun}*${rs} Failed to install zlib and/or zlib-devel\n"
 
      fi
 
    else
 
  printf " ${byel}*${rs} Installing $have_we\n"  && sudo dnf install $have_we || printf " ${bgrun}*${rs} Failed to install $have_we\n"
 
    ((cnt++))
 
    fi
 
  else
 
    printf " ${bgrun}*${rs} Searched and found $have_we.\n"
 
  fi
 
done
 
check_for_apps
 
}
 
 
# OK. This works in Manjaro, a Arch derivative.
 
function pacman_install()
 
{
 
helper_apps="as bison curl flex gcc git g++ make makeinfo pkg-config python zlib";
 
cnt=0
 
for have_we in $helper_apps;
 
do
 
  if ! [ -x "$(command -v $have_we)" ]
 
  then
 
    if [ $have_we = "as" ] # 'as' is in package binutils
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n" && sudo pacman -S binutils || printf " ${bred}*${rs} Failed to install $have_we\n"
 
    elif [ $have_we = "makeinfo" ] # 'makeinfo' is in package texinfo
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n" && sudo pacman -S texinfo || printf " ${bred}*${rs} Failed to install $have_we\n"
 
    elif [ $have_we = zlib ]
 
    then
 
      if ! pkg-config --exists zlib;
 
      then
 
        printf " ${byel}*${rs} Installing $have_we\n" && sudo pacman -S $have_we || printf "${bgrun}*${rs}Failed to install $have_we\n"
 
      fi
 
    else
 
  printf " ${byel}*${rs} Installing $have_we\n"  && sudo pacman -S $have_we || printf " ${bred}*${rs} Failed to install $have_we\n"
 
    ((cnt++))
 
fi
 
  else
 
    printf " ${bgrun}*${rs} Searched and found $have_we.\n"
 
  fi
 
done
 
check_for_apps
 
}
 
 
# This is OK.
 
function slapt-get_install()
 
{
 
helper_apps="as bison curl flex gcc g++ git make makeinfo pkg-config python zlib";
 
cnt=0
 
for have_we in $helper_apps;
 
do
 
  if ! [ -x "$(command -v $have_we)" ]
 
  then
 
    if [ $have_we = "as" ] # 'as' is in package binutils
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n" && sudo slapt-get --install binutils || printf " ${bred}*${rs} Failed to install $have_we\n"
 
    elif [ $have_we = "makeinfo" ] # 'makeinfo' is in package texinfo
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n" && sudo slapt-get --install texinfo || printf " ${bred}*${rs} Failed to install $have_we\n"
 
    elif [ $have_we = g++ ] # 'g++' is in package gcc-g++.
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n"  && sudo slapt-get --install gcc-g++ || printf "${bgrun}*${rs}Failed to install $have_we\n"
 
    elif [ $have_we = zlib ]
 
    then
 
      if ! pkg-config --exists zlib;
 
      then
 
        printf " ${byel}*${rs} Installing $have_we\n" && sudo slapt-get --install zlib || printf "${bgrun}*${rs}Failed to install $have_we\n"
 
      fi
 
    else
 
  printf " ${byel}*${rs} Installing $have_we\n" && sudo slapt-get --install $have_we || printf " ${bred}*${rs} Failed to install $have_we\n"
 
    ((cnt++))
 
    fi
 
  else
 
    printf " ${bgrun}*${rs} Searched and found $have_we.\n"
 
  fi
 
done
 
check_for_apps
 
}
 
 
# OK. This works in SME server, a CentOS derivative.
 
function yum_install()
 
{
 
helper_apps="as bison curl flex gcc git g++ make makeinfo pkg-config python zlib";
 
cnt=0
 
for have_we in $helper_apps;
 
do
 
  if ! [ -x "$(command -v $have_we)" ]
 
  then
 
    if [ $have_we = as ] # 'as' is in package binutils
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n"  && sudo yum install binutils || printf "${bgrun}*${rs}Failed to install $have_we\n"
 
    elif [ $have_we = makeinfo ] # 'makeinfo' is in package texinfo
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n"  && sudo yum install texinfo || printf "${bgrun}*${rs}Failed to install $have_we\n"
 
    elif [ $have_we = g++ ] # 'g++' is in package gcc-c++ possibly for all rpm packages.
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n"  && sudo yum install gcc-c++ || printf "${bgrun}*${rs}Failed to install $have_we\n"
 
    elif [ $have_we = zlib ]  # zlib has it's own package but requires zlib-devel for pkg-config to find it.
 
    then
 
      if ! pkg-config --exists zlib;
 
      then
 
        printf " ${byel}*${rs} Installing zlib and zlib-devel\n" && sudo yum install zlib zlib-devel || printf "${bgrun}*${rs}Failed to install zlib and/or zlib-devel\n"
 
      fi
 
    else
 
  printf " ${byel}*${rs} Installing $have_we\n"  && sudo yum install $have_we || printf "${bgrun}*${rs}Failed to install $have_we\n"
 
    ((cnt++))
 
    fi
 
  else
 
    printf " ${bgrun}*${rs} Searched and found $have_we.\n"
 
  fi
 
done
 
check_for_apps
 
}
 
 
# OK. This works in gecko, a opensuse derivative.
 
function zypper_install()
 
{
 
helper_apps="as bison curl flex gcc git g++ make makeinfo pkg-config python zlib";
 
cnt=0
 
for have_we in $helper_apps;
 
do
 
  if ! [ -x "$(command -v $have_we)" ]
 
  then
 
    if [ $have_we = as ] # 'as' is in package binutils
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n" && sudo zypper install binutils || printf "${bgrun}*${rs}Failed to install $have_we\n"
 
    elif [ $have_we = g++ ] # 'g++' is in package gcc-c++ possibly for all rpm packages.
 
    then
 
      printf " ${byel}*${rs} Installing $have_we\n"  && sudo zypper install gcc-c++ || printf "${bgrun}*${rs}Failed to install $have_we\n"
 
    elif [ $have_we = zlib ] # 'zlib' is in package libz1 possibly for all rpm packages.  zlib-devel is also needed.
 
    then
 
      if ! pkg-config --exists zlib;
 
      then
 
        printf " ${byel}*${rs} Installing $have_we\n" && sudo zypper install libz1 && sudo zypper in zlib-devel || printf "${bgrun}*${rs}Failed to install $have_we\n"
 
      fi
 
    else
 
  printf " ${byel}*${rs} Installing $have_we\n" && sudo zypper install $have_we || printf "${bgrun}*${rs}Failed to install $have_we\n"
 
    ((cnt++))
 
    fi
 
  else
 
    printf " ${bgrun}*${rs} Searched and found $have_we.\n"
 
  fi
 
done
 
check_for_apps
 
}
 
 
function find_pm()
 
{
 
printf "\n * * * * * * * * * ${pblue}Searching for a package management tool${rs} * * * * * * * * * * \n\n"
 
package_apps="apt apt-get dnf pacman slapt-get pkg yum zypper"; # Total PMs is 8.
 
cnt_pm=0
 
for have_got in $package_apps;
 
do
 
  if [ -x "$(command -v $have_got)" ]
 
  then
 
      printf " ${bgrun}*${rs} Found $have_got\n"
 
      $have_got"_install"
 
      break
 
  else
 
      ((cnt_pm++))
 
      printf " ${bred}*${rs} No $have_got\n"
 
  fi
 
done
 
 
if [ $cnt_pm -ge 8 ]
 
then
 
  printf "\n ${bred}*${rs} Sorry, your package Manager is not in the list.\n"
 
  printf "\n                          These are the required app(s)\n\n"
 
  check_for_apps
 
fi
 
}
 
 
function check_for_apps()
 
{
 
helper_apps="as bison curl flex gcc git g++ make makeinfo pkg-config python";
 
cnt=0
 
for have_we in $helper_apps;
 
do
 
  if ! [ -x "$(command -v $have_we)" ]
 
  then
 
    printf "${dyel}%-.71s${rs} ${bred}%s${rs}\n" " * Searched for $have_we ..................................................... " "$mis"
 
    ((cnt++))
 
  else
 
    printf "%-.73s ${bgrun}%s${rs}\n" " * Searched for $have_we ..................................................... " "$got"
 
  fi
 
done
 
  if pkg-config --exists zlib;
 
  then
 
    printf "%-.73s ${bgrun}%s${rs}\n" " * Searched for zlib ..................................................... " "$got"
 
  else
 
    printf "${dyel}%-.71s${rs} ${bred}%s${rs}\n" " * Searched for zlib ..................................................... " "$mis"
 
    ((cnt++))
 
  fi
 
echo " " # space
 
  if ((cnt > 0));
 
  then
 
    printf " ${bred}*${rs} The script was unable to install %d ${bred}MISSING${rs} app(s).\n" "$cnt"
 
    printf " ${byel}*${rs} You will have to try and install what is missing yourself.\n"
 
  else
 
    printf " ${bgrun}OK${rs} Everything looks good to proceed.\n\n"
 
  fi
 
}
 
# After checking for sudo, the execution comes here.
 
needed_apps="as bison curl flex gcc git g++ make makeinfo pkg-config python";
 
for is_in in $needed_apps;
 
do
 
  if ! [ -x "$(command -v $is_in)" ]
 
  then
 
    printf " ${bred}*${rs} You have one or more missing apps that need to be installed.\n"
 
    find_pm
 
    break
 
  else
 
    printf " ${bgrun}*${rs} Found $is_in\n"
 
    if ! pkg-config --exists zlib;
 
    then
 
      printf " ${bred}*${rs} zlib is missing\n"
 
      find_pm
 
    break
 
    fi
 
  fi
 
done
 
printf "\n  * * * * * * * * * * * * * * * * * * ${pblue}Finished${rs} * * * * * * * * * * * * * * * \n"
 
</pre>
 
 
To use the script, just copy from here and paste it into a text editor, then save it with the file extension of '''sh'''. You will need to make this script executable by typing '''chmod +x (path) script name''' at the command prompt in a terminal window. Example: '''chmod +x /home/oldman/app-checker.sh'''
 
 
 
===Create the Tutorial working environment===
 
This script is intended to be used, to automate (but needs user input) the setting up of a working environment (all the directory folders, software and ReactOS source code) as described in the Layman's guides.
 
 
The directory structure.
 
<pre>
 
/home/oldman/RosBuild
 
+-- Compiled
 
+-- Debug
 
+-- ISO-images
 
+-- Required-Software
 
+-- RosBE
 
+-- Source
 
</pre>
 
 
The script starts by searching for the required software, including software used by the RosBE installer script. If it finds anything missing that is required, it will terminate, having first listed the <span style="color:green">FOUND</span> and the <span style="color:red">MISSING</span> software.
 
 
When you have installed all the missing software, you can safely run the script again. It will again list all the required software, but this time they should all be found, else it terminates again for you to install any missing items of software.
 
 
When all the required software is found it will then prompt you for a path to the directory where you wish to install the testing environment. It will check to see if it is a valid path and the user has the correct privileges. '''Note''': there is an option for a '''default path''' for a '''none root''' user (see the directory structure above), the default is '''/home/user'''; the user in the example shown above in the directory structure, is '''oldman'''.
 
 
Next it looks for an installed version of '''RosBE''', in two locations; if it fails to find RosBE installed, it will then look for the downloaded RosBE tar file, if that is not found, it will download and unpack it, then run the RosBE installer. Once the installer start to compile RosBE, there will be no more user input required for the duration of the script. If any errors occur, then the script will terminate with an error message
 
 
After RosBE is installed, the next step is the cloning of the '''ReactOS''' source from '''github''' into the newly created Source directory. When the cloning is complete, it writes the version number to '''Revision.txt'''.
 
 
After cloning the source, it creates the '''update.sh''' script for the user to use, whenever they want to update the local source. It updates the source and will write info into two different text files; '''update.txt''', which saves the commit messages from the updated source and '''Revision.txt''', which stores the revision number, the same Revision.txt file that was created and written to earlier, when the source was first cloned.
 
 
 
The script.
 
<code style="font-size:50%;"><pre>
 
 
#!/bin/bash
 
#######################################################################################################
 
#      This script automates the setting up of a working environment, as per the Layman's guides.    #
 
# I hate EULAs.  ©Nobody.  Use at your own risk! It worked for me and did what it was intended to do. #
 
#######################################################################################################
 
clear
 
printf "\033[0;32m\n"
 
printf  "::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::\n"
 
printf  "::  This script will setup a working environment similar to that described  ::\n"
 
printf  "::    in the Layman's guides at https://reactos.org/wiki (Unix sections)    ::\n"
 
printf  "::        Should only need to be run once, but can be safley run again.      ::\n"
 
printf  "::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::\n"
 
printf "\033[0m\n"
 
# ############################### Define the variables in this section ################################
 
 
# Text colour
 
bwhit='\033[1;37m' # Bright White
 
pblue='\033[1;4m'  # Pale Blue
 
bred='\033[1;31m'  # Bright Red
 
bgrun='\033[1;32m' # Bright Green
 
byel='\033[1;33m'  # Bright Yellow
 
dyel='\033[0;33m'  # Dark Yellow
 
rs='\033[0m'      # Reset the text back to the default
 
 
# Messages
 
mis="MISSING"
 
got="FOUND"
 
 
# Directories to be created
 
RB="/RosBuild"
 
RBcpl="/RosBuild/Compiled"
 
RBdbg="/RosBuild/Debug"
 
RBiso="/RosBuild/ISO-images"
 
RBreq="/RosBuild/Required-Software"
 
RBrbe="/RosBuild/RosBE"
 
RBsrc="/RosBuild/Source"
 
 
# Links to external software (you only need to update here)
 
Rbe="https://sourceforge.net/projects/reactos/files/RosBE-Unix/2.1.2/RosBE-Unix-2.1.2.tar.bz2/download"
 
Ros_BE="RosBE-Unix-2.1.2.tar.bz2"
 
 
Rsrc="https://github.com/reactos/reactos.git"
 
 
# #########################################  Function section #########################################
 
 
function check_for_apps()
 
{
 
helper_apps="as bison curl flex gcc git g++ make makeinfo python sudo";
 
cnt=0
 
for have_we in $helper_apps;
 
do
 
  if ! [ -x "$(command -v $have_we)" ]
 
  then
 
    printf "${dyel}%-71s${rs} ${bred}%s${rs}\n" " * Searched for $have_we ..................................................... " "$mis"
 
    ((cnt++))
 
  else
 
    printf "%-.73s ${bgrun}%s${rs}\n" " * Searched for $have_we ..................................................... " "$got"
 
  fi
 
done
 
  if [ -e "/usr/bin/pkg-config" ]
 
    printf "%-.73s ${bgrun}%s${rs}\n" " * Searched for pkg-config ..................................................... " "$got"
 
  then
 
    if pkg-config --exists zlib;
 
    then
 
      printf "%-.73s ${bgrun}%s${rs}\n" " * Searched for zlib ..................................................... " "$got"
 
    else
 
      printf "${dyel}%-.71s${rs} ${bred}%s${rs}\n" " * Searched for zlib ..................................................... " "$mis"
 
  else
 
    printf "${dyel}%-.71s${rs} ${bred}%s${rs}\n" " * Searched for pkg-config ..................................................... " "$mis"
 
  ((cnt++))
 
  fi
 
echo " " # space
 
  if ((cnt > 0));
 
  then
 
    printf " Please install the above %d ${bred}MISSING${rs} app(s), then run the script again!\n" "$cnt"
 
    exit 1
 
  else
 
    printf " ${bgrun}OK${rs} Everything looks good to proceed.\n\n"
 
  fi
 
}
 
 
function get_path()
 
{
 
    printf " ${byel}*${rs} Please enter a valid path for user $USER: \n"
 
    if ! [ "$(id -u)" = '0' ]; # Hide from root user
 
    then
 
      printf "  or press the ${byel}Enter${rs} key for the default path of ${byel}/home/$USER${rs}.\n\n"
 
    fi
 
    read PTD
 
    if test -z "$PTD" # empty
 
    then
 
      PTD=/home/$USER
 
    fi
 
    if test ! -d "$PTD"
 
    then
 
      printf "\n ${bred}ERROR${rs}: The path ${bwhit}$PTD${rs} does exist!\n\n" && get_path
 
    fi
 
    if test ! -w "$PTD"
 
    then
 
      printf "\n ${bred}ERROR${rs}: You do not have write permission for this path!\n\n" && get_path
 
    fi
 
}
 
 
function make_dirs()
 
{
 
    get_path
 
  if test ! -z "$PTD" && test -d "$PTD" && test -w "$PTD";
 
  then
 
    test ! -d "$PTD$RB" && mkdir $PTD$RB && printf " ${byel}*${rs} Created directory RosBuild.\n"
 
    test ! -d "$PTD$RBcpl" && mkdir $PTD$RBcpl && printf " ${byel}*${rs} Created directory Compiled.\n"
 
    test ! -d "$PTD$RBdbg" && mkdir $PTD$RBdbg && printf " ${byel}*${rs} Created directory Debug.\n"
 
    test ! -d "$PTD$RBiso" && mkdir $PTD$RBiso && printf " ${byel}*${rs} Created directory ISO-images.\n"
 
    test ! -d "$PTD$RBreq" && mkdir $PTD$RBreq && printf " ${byel}*${rs} Created directory Required-Software.\n"
 
    test ! -d "$PTD$RBrbe" && mkdir $PTD$RBrbe && printf " ${byel}*${rs} Created directory RosBE.\n"
 
    test ! -d "$PTD$RBsrc" && mkdir $PTD$RBsrc && printf " ${byel}*${rs} Created directory Source.\n"
 
    printf "\n ${bgrun}*${rs} The directories were created in ${bwhit}%s${rs}\n\n" "$PTD"
 
  fi
 
}
 
 
function get_rosbe()
 
{
 
  cd $PTD/RosBuild/Required-Software
 
  rbe_found=""
 
  if [[ -d "/usr/local/RosBE" ]] || [[ -e "$PTD/RosBuild/RosBE/RosBE.sh" ]]
 
# returns 'true' if /usr/local/RosBE/RosBE.sh or $PTD/RosBuild/RosBE/RosBE.sh exists
 
  then
 
    rbe_found="ok"
 
    printf " ${dyel}*${rs} No need to download RosBE, it was found to be installed.\n\n"
 
  else
 
    if [ ! -e "$Ros_BE" ]
 
# returns 'true' if RosBE-Unix-2.1.2.tar.bz2 does not exist
 
    then
 
      printf " ${byel}*${rs} Down-loading RosBE.\n\n"
 
      curl --cookie nada --location $Rbe > RosBE-Unix-2.1.2.tar.bz2 || return $?
 
      printf "\n ${byel}*${rs} RosBE download completed.\n\n"
 
    else
 
      printf " ${dyel}*${rs} The RosBE download package was found.\n\n"
 
    fi
 
  fi
 
}
 
 
function install_rosbe()
 
{
 
  if [ -e "$Ros_BE" ] && [ -z ${rbe_found} ] # rbe_found = RosBE is installed
 
  then # 'true' if RosBE-Unix-2.1.2.tar.bz2 exists and r_found is empty (RosBE not installed)
 
    while true
 
    do
 
      printf " ${byel}*${rs} Extracting RosBE "
 
      tar -xjf $Ros_BE --checkpoint=200 --checkpoint-action=. && printf " ${bgrun}Success${rs}\n\n" || return $?
 
    break # the above produces 'Extracting RosBE ................................ Success'
 
    done
 
    if [ -d "$PTD$RBreq/RosBE-Unix-2.1.2" ] && [ -z ${rbe_found} ] # RosBE download file is extracted but not installed
 
    then # 'true' if RosBe-Unix-2.1.2 dir exists and RosBE-Unix-2.1.2.tar.bz2 does not exist ($rbe_found is unset or empty)
 
      if ! [ "$(id -u)" = '0' ]; # Hides this from root user
 
      then
 
        printf "                ${byel}* * * * * * * *${rs} PLEASE READ THIS ${byel}* * * * * * * *${rs}\n"
 
        printf "  ${byel}*${rs} The RosBE script will inform you that  ${dyel}User is not \"root\"${rs} and ask you\n"
 
        printf "  ${dyel} Do you really want to continue? (yes/no)${rs}; type ${bwhit}yes${rs}. This will allow\n"
 
        printf "    you to install to your chosen path of ${bwhit}$PTD$RBrbe${rs}.\n\n"
 
        sleep 5
 
        printf "                      ${bred}* * * * * * *${rs} ${bwhit}WARNING${rs} ${bred}* * * * * *${rs}\n"
 
        printf " ${dyel}*${rs} If after choosing to continue, you select to have RosBE installed to the\n"
 
        printf "  default path of ${bwhit}/usr/local/RosBE${rs}, then you may get this error:\n"
 
        printf "  ${dyel}Installation directory \"/usr/local/RosBE\" is not writable, aborted!${rs} This\n"
 
        printf "  is due to ${bwhit}$USER${rs}'s lack of permissions! Both scripts will then terminate!\n\n"
 
        printf " ${byel}*${rs} Do you want to run the RosBE installer as root to give you a choice?\n\n"
 
        read -p "  Please answer yes or just press the Enter key for no: " ans
 
          case "$ans" in
 
            y|yes|Y|YES|Yes)
 
            printf "\n ${byel}*${rs} Starting the RosBE install script.\n\n"
 
            cd "$PTD/RosBuild/Required-Software/RosBE-Unix-2.1.2"
 
            sudo ./RosBE-Builder.sh || return $?
 
            printf "\n ${bgrun}*${rs} RosBE is now installed.\n\n"
 
          ;;
 
          esac
 
        fi
 
      printf "\n ${byel}*${rs} Starting the RosBE install script.\n\n"
 
      cd "$PTD/RosBuild/Required-Software/RosBE-Unix-2.1.2"
 
      ./RosBE-Builder.sh || return $?
 
      printf "\n ${bgrun}*${rs} RosBE is now installed.\n\n"
 
    else
 
      printf " ${dyel}*${rs} No need to install RosBE, it was found to be installed.\n\n"
 
    fi
 
  else
 
    printf " ${dyel}*${rs} No need to install RosBE, it was found to be installed.\n\n"
 
  fi
 
}
 
 
function clone_source()
 
{
 
  if [ ! -d "$PTD$RBsrc/reactos" ]
 
  then # (true if not exists) Test for the existence 'Source/reactos' directory before cloning the source.
 
    cd $PTD/RosBuild/Source
 
    printf " ${byel}*${rs} Cloning the ReactOS source tree from Github into the Source directory.\n\n"
 
    git clone https://github.com/reactos/reactos.git || return $?
 
    printf "\n ${bgrun}*${rs} The ReactOS source was successfully cloned to $PTD$RBsrc\n\n"
 
    if [ -d "$PTD/RosBuild/Source/reactos" ] && [ ! -e "$PTD$RB/Revision.txt" ]
 
      # Test for the directory folder reactos and the existance of the Revision.txt.
 
    then # true if 'reactos' dir exists and Revision.txt does not exist
 
      cd $PTD/RosBuild/Source/reactos
 
      day_name=`date "+%A"`
 
      hr_min=`date "+%H:%M"` 
 
      day_date=`date "+%Y-%m-%d"`
 
      echo "  ------- $day_name at $hr_min - $day_date -------"  1>  $PTD/RosBuild/Source/Revision.txt
 
      # Find the revision number and write it to revision.txt.
 
      git describe 1>> $PTD/RosBuild/Revision.txt # The actual source files are in Source/reactos.
 
      printf " ${byel}*${rs} The day, time, date and revision number have been written to ${bwhit}$PTD$RB${rs}\n\n"
 
    fi
 
  else
 
    printf " ${bred}*${rs} $PTD$RBsrc/${dyel}reactos${rs} exists already!\n\n"
 
    printf " ${dyel}*${rs} If the clone process terminated before it finished,\n"
 
    printf "  then delete the ${dyel}reactos${rs} directory and run the script again.\n\n"
 
  fi
 
}
 
 
function make_script()
 
{
 
# Make a script for the user to updated the source code required.
 
# Check here to see if the script 'update-source.sh' has already been created.
 
  if [ ! -e  "$PTD/RosBuild/update-source.sh" ]
 
  then
 
    echo "printf \"::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::\n\"" 1> $PTD/RosBuild/update-source.sh
 
    echo "printf \":          Automates the updating of your local source tree as per the tutorial.                :\n\"" 1>> $PTD/RosBuild/update-source.sh
 
    echo "printf \": I hate EULAs.  ©Nobody. Use at your own risk! It worked for me and did what I wanted it to do. :\n\"" 1>> $PTD/RosBuild/update-source.sh
 
    echo "printf \"::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::\n\n\"" 1>> $PTD/RosBuild/update-source.sh
 
    echo "day_name=\`date \"+%A\"\`" 1>> $PTD/RosBuild/update-source.sh
 
    echo "hr_min=\`date \"+%H:%M\"\`" 1>> $PTD/RosBuild/update-source.sh
 
    echo "day_date=\`date \"+%Y-%m-%d\"\`" 1>> $PTD/RosBuild/update-source.sh
 
    echo "printf \" * Checking for source code changes and additions! Please give it time to complete.\n\n\"" 1>> $PTD/RosBuild/update-source.sh
 
    echo "cd $PTD/RosBuild/Source/reactos" 1>> $PTD/RosBuild/update-source.sh
 
    echo "git  pull origin 1>> $PTD/RosBuild/update.txt" 1>> $PTD/RosBuild/update-source.sh
 
    echo "echo \" ------- \$day_name at \$hr_min - \$day_date ------- \" 1>> $PTD/RosBuild/Revision.txt" 1>> $PTD/RosBuild/update-source.sh
 
    echo "echo \" ------- \$day_name at \$hr_min - \$day_date ------- \" 1>> $PTD/RosBuild/update.txt" 1>> $PTD/RosBuild/update-source.sh
 
    echo "# Find the revision number and write it to Revision.txt." 1>> $PTD/RosBuild/update-source.sh
 
    echo "git describe 1>> $PTD/RosBuild/Revision.txt" 1>> $PTD/RosBuild/update-source.sh
 
    echo "printf \" * Update completed. Please see /home/oldman/RosBuild/Revision.txt and update.txt\n\n\"" 1>> $PTD/RosBuild/update-source.sh
 
    if [ -e "$PTD/RosBuild/update-source.sh" ]
 
    then
 
      printf " ${byel}*${rs} A bash script '${byel}update-source.sh${rs}' has been created in ${bwhit}$PTD$RB${rs}.\n"
 
      printf "  You can use this script when you want to update the source tree.\n\n"
 
      chmod +x $PTD/RosBuild/update-source.sh # make the script executable.
 
    else
 
      printf " ${bred}*${rs} The creation of the 'update-source.sh' script ${bred}FAILED${rs}.\n" # failure
 
    fi
 
  else
 
    printf " ${dyel}*${rs} The script was found, so no need to create it!\n\n"
 
  fi
 
}
 
 
################################################## control section ##################################################
 
 
printf " * * * * * * * * * * * * ${pblue}Searching for needed helper apps${rs} * * * * * * * * * * *\n\n"
 
check_for_apps
 
printf " * * * * * * * * * * * * * * ${pblue}Create the directories${rs} * * * * * * * * * * * * * *\n\n"
 
make_dirs
 
printf " * * * * * * * * * * * * * * * * ${pblue}Download RosBE${rs} * * * * * * * * * * * * * * * *\n\n"
 
get_rosbe
 
if ! [ $? -eq 0 ] # 0 = success, so not equal to 0 = failure
 
then
 
  printf "\n ${bred}*${rs} The down-loading of the RosBE ${bred}FAILED${rs}!\n\n" && exit 1
 
fi
 
printf " * * * * * * * * * * * * * * * * ${pblue}Install RosBE${rs} * * * * * * * * * * * * * * * *\n\n"
 
install_rosbe
 
if ! [ $? -eq 0 ]
 
then
 
  printf "\n ${bred}*${rs} The installation of RosBE ${bred}FAILED${rs}!\n\n" && exit 1
 
fi
 
printf " * * * * * * * * * * * *  ${pblue}Clone the ReactOS source tree${rs} * * * * * * * * * * * *\n\n"
 
clone_source
 
if ! [ $? -eq 0 ]
 
then
 
  printf "\n ${bred}*${rs} The cloning of the ReactOS source ${bred}FAILED${rs}!\n\n" && exit 1
 
fi
 
printf " * * * * * * * * * * *  ${pblue}Create the update-source.sh script${rs} * * * * * * * * * * *\n\n"
 
make_script
 
printf " ${byel}* * *${rs} The working environment should now be all setup and ready to use. ${byel}* * *${rs}\n\n"
 
printf "\n * * * * * * * * * * * * ${pblue}This script has now terminated!${rs} * * * * * * * * * * * *\n\n"
 
 
 
</pre></code>
 
 
To get the script, just copy from here and paste it into a text editor, then save it with the file extension of '''sh''' and run it at your leisure. It will save you a lot of typing (if you are happy with the directory names) and only needs to be run once to create a working environment, but can safely be run again if something did fail. You will need to make this script executable by typing '''chmod +x''' (path) script name at the command prompt in a terminal window. Example: '''chmod +x''' /home/oldman/make-workspace'''.sh'''
 
 
 
===Update the local source===
 
This script is similar to the update script which was created by the last script above. It automates the updating of your local source tree using the directory structure shown in the tutorial. When the update is complete, it will create a file '''/home/RosBuild/revision.txt''' with the date and revision number.
 
To use it, copy and paste it into a text editor, change the paths to suit your own directory tree and the file names to your own choice, then save as a '''.sh''' file with a name of your choice.
 
You will need to make this script executable by typing '''chmod +x''' (path) script name at the command prompt in a terminal window.
 
 
<code><pre>
 
#!/bin/bash
 
# Automates the updating of your local source tree as per the tutorial.
 
RevDate=$(date)
 
# Run git from the reactos folder.
 
cd /home/RosBuild/source/reactos/
 
# Do an update and write the output info to update.txt.
 
git pull origin 1>> /home/RosBuild/update.txt
 
# Write the current date to the update.txt.
 
echo "Update completed ------------ $RevDate" 1>> /home/RosBuild/update.txt
 
echo "update completed"
 
# Write the current date to the revision.txt.
 
echo "$RevDate" 1>> /home/RosBuild/revision.txt
 
# Get the current revision info and write it to revision.txt.
 
# The info will be in this format 0.4.8-dev-51-gbe1155f294
 
git describe 1>> /home/RosBuild/revision.txt
 
# Draw a line underneath to separate the revision updates.
 
echo "~~~~~~~~~~~~~~~~~~~~~~~~~" 1>> /home/RosBuild/revision.txt
 
echo 'done'
 
</pre></code>
 
 
 
<p style="font-size:150%;border-top:3px solid #a00050;"></p>
 
 
Revised and updated March 2017.
 
 
Minor text additions and the addition of some Unix subsections - August 2017.
 
 
Added debugging with VirtualBox through a virtual serial line (Windows and Unix) September 2017.
 
 
Updated for Git, where necessary. October 2017.
 
 
Added a new section with some scripts. January 2018.
 
 
 
==Links==
 
==Links==
 
More tutorials can be found at:  
 
More tutorials can be found at:  

Latest revision as of 17:31, 12 January 2019