Difference between revisions of "User:Oldman"

From ReactOS Wiki
Jump to: navigation, search
Line 121: Line 121:
 
* A nullmodem cable to connect both computers.
 
* A nullmodem cable to connect both computers.
 
===Software===
 
===Software===
Win32 Putty - http://the.earth.li/~sgtatham/putty/latest/x86/puttytel.exe
+
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 uses may be able to get Putty through their Package Manager.
  
 
=== Setting up Putty. ===
 
=== Setting up Putty. ===

Revision as of 09:07, 25 November 2015

My aim is to make these tutorials simple to understand; I hope that I have achieved that and you find them helpful.

A layman's guide - Getting an ISO to test

This should not be needed, but this is a layman's guide, so I will describe where to get your ReactOS iso from. On the front page at https://www.reactos.org/ on the right hand side of the page, you will see the 3 links shown in the following image.

Click on the Daily Builds button, which will take you to another page, there you will find a list of the latest built iso images, as shown in the next two images, below.

Note:
The Downloads.... button is the link to the official releases. Unless there as been a new release in the last week, they are best not used for testing, because they very quickly become out of date, due to the continual development of ReactOS.



The right image shows only the debug ISOs, which also shows that, not all versions are created for each revision. For debuging purposes you will have to choose a dbg or a dbg-msvc version. The bootcd is for installing ReactOS, and currently (February 2015) the livecd cannot be used to install ReactOS and is used for evaluation of the OS.


A layman's guide - How to compile ReactOS.

This tutorial uses Tortoise svn in Windows XP; start by down-loading it from http://tortoisesvn.net/downloads.html and installing it.

Create the following directories on your hard drive: (They can be in C: or D: or any other drive partition, and can be enclosed within another directory, for example D:\ReactOSDevelopment or C:\ROS).

1. \source (the name does not matter - down-load the source tree to this folder).

2. \compiled (the name does not matter - this is the output folder where the binaries will go).

3. \RosBE (install the ReactOS Build Environment into this folder, but only needed if you have not already got it installed elsewhere)

You should now have something like the following examples, which use the C: drive;

Example No1

C:\source

C:\compiled

C:\RosBE

or

Example No2

D:\ReactOSDevelopment\source

D:\ReactOSDevelopment\compiled

D:\ReactOSDevelopment\RosBE

Using example No2, checkout the source tree at svn://svn.reactos.org/reactos/trunk/ into D:\ReactOSDevelopment\source with Tortoise [1] by right clicking on the source folder and selecting SVN Checkout.... At the next window[2], type svn://svn.reactos.org/reactos/trunk/ into the first input box (note: there is a folder icon covering the sv in this screenshot), in the next input box select or type D:\ReactOSDevelopment\source and the rest should be as shown in the screenshot.

Install the ReactOS Build Environment [5] [6] [7] (a link to the latest version can be found here: https://www.reactos.org/wiki/ReactOS_Build_Environment) into D:\ReactOSDevelopment\RosBE (when installing, un-check the PowerShell option and select to have a desktop shortcut), then start it and from it's command prompt: (If you did not install with a desktop shortcut selected, then open a command prompt window and navigate to D:\ReactOSDevelopment\RosBE and type RosBE to start it.)

1. Navigate to D:\ReactOSDevelopment\compiled and type D:\ReactOSDevelopment\source\reactos\configure ninja

2. Still within D:\ReactOSDevelopment\compiled type ninja bootcd

or

3. Still within D:\ReactOSDevelopment\compiled type ninja livecd

or

4. Still within D:\ReactOSDevelopment\compiled type ninja hybridcd

Now you should find the bootcd and/or the livecd and/or hybridcd in D:\ReactOSDevelopment\compiled\reactos.

If you have problems compiling after you have updated your local source tree, try typing ninja clean and then start again at step 1 above.



Compiling - Screenshots (a picture is worth a thousand words)

Getting the source with Tortoise

Configuring and installing RosBE


A layman's guide - How to get a debug log.

This is a layman's guide to using the Ros debugger to get a debug log when ReactOS is started in Debug [1] mode (for other modes see Variations below).

Hardware requirements:

  • A test computer with a serial port.
  • A second computer with a serial port and Putty installed (or simular 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 uses 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 to these values:
Serial line = COM1
Speed = 115200
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 [2] [3] 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 key combination of Tab+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+k - this command halts the system so you can enter commands into the debugger.
bt - this command gives a backtrace; use it when ROS enters the debugger (see below).
cont - this is short for continue.
set condition * 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 [4] screenshot below):
Entered debugger on last-chance exception (Exception Code: 0xc0000001) (Unknown/User defined exception)
kdb>

Getting a backtrace:

When ROS enters the debugger, then you need to enter bt at the command prompt, like so: kdb:> bt [4] and press enter on the keyboard. You may see this
--- Press q to abort, any other key to continue --- [5]
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 [1], then press Tab+k on your keyboard, then type set condition * first always at the command prompt, then type cont [6]. This will make ROS enter the debugger on every exception, which it will do many times, and each time you will have to type bt then cont.

Note 1 If you are testing an app, then it is best to wait until you are ready to run the app before setting the condition to first always, else you could be overwhelmed with the ROS entering the debugger.

No working keyboard!

Currently (Jan 2015) usb support is problematic, so your keyboard may not work! If you have found that your usb keyboard does not work with ReactOS, and ROS 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: livecd-66078-dbg.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:

Don't use Tab+k and bt to get a backtrace, when the ROS does not automatically enter the debugger, thinking you are going to get some more useful info for the dev's to work with, which I have done in the past; the info is useless!

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 - Ros revision number", for example "gimp-1.0.4-R65099".

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 ROS, which can output extra debug info. In use, the difference is in the keyboard input, where you can only use Tab + k on the ROS 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 ROS 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 ROS test computer's hard drive. Any keyboard input is done on the ROS 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 (a picture is worth a thousand words)

A layman's guide - How to create a Jira Issue for your bug.

From the ReactOS.org front page, go to the jira page (https://jira.reactos.org/secure/Dashboard.jspa) by clicking on the Bugtracker link on the navigation bar at the top of most pages. If you successfully followed the link you should now be at the Dashboard page of ReactOS JIRA, on the right side of the page [1], 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.

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 days and try again. There is also 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.

When you have logged in, the next thing to do, is a search to see if your bug has been reported already. Use the Quick Search box at the far right of the navigation bar.

To create a bug report (called an Issue in Jira), click on the "+ Create Issue" on the navigation bar at the top [3], which will open a Create Issue form [4].

Give a short description of the problem in Summary (this with 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 where it occurred (include the down-load link to any software), then describe what happens and how to replicate the problem.

If you get a debug log or take a photo or video, use the Browse button in 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.

Jira Issue - Screenshots (a picture is worth a thousand words)

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.

Go to ReatOS Jira and log in. Then go to the Issues [2] page and select Reported by Me [5] and your Issues will be shown. Select the Issue you want to add more to. Then use either the Attach Files [6] link on the menu bar that is just below the report name, or further down at Attachments [7], the plus sign. Both will open the Attach Files form [8], where you will need to use the Browse button to upload your files, the Comment box to 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.

If you only want to add more information, or to reply to a question from a developer, use the Comment button [9] at the bottom left of the page, which will open a Comment box. When you have finished writing in the Comment box, use the Add buttom [10] (which is where the Comment button was) to attach it to the report.

Screenshots (a picture is worth a thousand words)

A layman's guide - Regression testing: finding the guilty revision.

We will assume that revision 68000 has a regression, so it is the ' bad ' revision, you will need to find a ' good ' revision.

Use revision 68000 as the bad reference point, go back in increments of 100, 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 half way point between the two revisions and test that revision; 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 known ' good ' revision and the last ' bad ' revision until they are next to each other, for example: *****5 (bad) and *****6 (good).


A layman's guide - log2lines.

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-66048.log and bootcd-66048-dbg.iso).

Using the example from above, you would type this at the RosBE command prompt:

D:\DebugWork\RosBE>log2lines -m -d D:\DebugWork\bootcd-66048-dbg.iso <D:\DebugWork\explorer-66048.log> D:\DebugWork\explorer-66048-new.log

The prefix -m puts a * at the front of the tranlated line, and the prefix -d indicates that it is a directory or iso image.

If you have RosBE already installed elsewhere, then, using the same folder and files as in the example above, you would just open RosBE and type log2lines -m -d D:\DebugWork\bootcd-66048-dbg.iso <D:\DebugWork\explorer-66048.log> D:\DebugWork\explorer-66048-new.log at the command prompt.


log2lines - Screenshots (a picture is worth a thousand words)



Links

More tutorials can be found at:

https://www.reactos.org/forum/viewforum.php?f=22

https://www.reactos.org/wiki/Category:Tutorial

https://www.reactos.org/wiki/Subversion/Using_TortoiseSVN

https://www.reactos.org/wiki/Testing_Introduction

https://www.reactos.org/wiki/Build_Environment