Difference between revisions of "User:Oldman"

From ReactOS Wiki
Jump to: navigation, search
m
m
Line 507: Line 507:
 
Explanation:
 
Explanation:
  
'''log2lines''' Executes log2lines.
+
'''log2lines''' .. Executes log2lines.
  
'''switches'''   '''-m''' Marks the translated line with an <span style="font-size:110%>'''*'''</span> and '''-d''' is for directory.
+
'''switches''' .. '''-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.
+
'''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 log that you got for the bug.
+
'''<old log>''' .. This is the location and name of the original log that you got for the bug.
  
'''new log''' This is the location and name for the modified log. It will be written with that name and at that location.
+
'''new log''' .... This is the location and name for the modified log. It will be written with that name and at that location.
  
 
<small>See also the explanation in the main section above.</small>
 
<small>See also the explanation in the main section above.</small>

Revision as of 17:50, 12 August 2017

Having found the official tutorials sometimes hard to understand and ambiguous, my aim was to make these tutorials simple to understand; I hope that I have achieved that and you find them helpful.

What I have written here is from personal experience; if I cannot do it myself, then I cannot write about it.


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.

Release ISO

On the front page at https://www.reactos.org/ on the right hand side of the navigation bar, you will find two download buttons [No1], 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 [No2].

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.

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  and more..., the box shown in image No3a.

If you click on the Daily builds button, it will close the Gallery section and open the Daily builds section [No3b], to reveal the Download here! button. If you then click on the Download here! button, it will take you to the Trunk Builds page [No4].

Where you can, not only get the latest ISO image, but you can also get some ISO images going back up to 5 years.

Trunk Builds page explained [No4]

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 Show button. This is useful when you want to find a ISO from the past.

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 Show button updates the list of files.

  • Debug Booot CDs = bootcd-74033-dbg-msvc.7z and bootcd-74033-dbg.7z
  • Debug Live CDs = livecd-74033-dbg-msvc.7z and livecd-74033-dbg.7z
  • Release Boot CDs = bootcd-rel.7z
  • Release Live CDs = livecd-rel.7z


File Name - bootcd is for installing onto the hard drive, the livecd is for running the OS without putting anything onto the hard drive, dbg means it has code within it to output debug information and msvc is short for Microsoft Visual C and is not covered in this guide.

Size and Last changed, are self explanatory.


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 No4.



A layman's guide - How to compile ReactOS.

In this tutorial there is also a Unix based subsection.

Start this tutorial by down-loading Tortoise svn from http://tortoisesvn.net/downloads.html and installing it.

You will then 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 checkout 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:\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... (see Note). 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. See also [3] [4]

Install the ReactOS Build Environment [5] [6] [7] (a link to the latest version (Windows and Unix) can be found here: https://www.reactos.org/wiki/ReactOS_Build_Environment) into D:\ReactOSDevelopment\RosBE (I selected to have a desktop shortcut. See also Note), then start it, and from it's command prompt: [8]

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

or if want all three ISO images

5. Still within D:\ReactOSDevelopment\compiled type ninja bootcd livecd 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.

Note: Once you have done a SVN Checkout, it will show SVN Update the next time.
Note: If you did not install RosBE with a desktop shortcut selected, then open a command prompt window and navigate to D:\ReactOSDevelopment\RosBE and type RosBE to start it.

Compiling - Screenshots

Getting the source with Tortoise

Right click on the source folder, then select SVN Checkout/Update.


Checkout/Update from svn://svn.reactos.org/reactos/trunk/ to D:\ReactOSDevelopment\source.


This shows a successful checkout.


This shows the folder structure in D:\ReactOSDevelopment\source\ after a successful checkout.


Configuring and installing RosBE

Compiling

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.


How to compile ReactOS - Unix subsection

I am using Puppy Slacko 6.3.2 and /root is my home directory, so I will substitute /root with /home in the text, for the sake of the other variations of Unix.

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 the window [9], for the menu, Window - Terminal Here [10].

In the terminal window, run the builder script by typing ./RosBE-Builder.sh

If it reports any missing tools [11], you will need to install them (the package devx.sfs worked for me).

Then run the script as before, and if it reports all tools OK [12], 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/command prompt window and use svn, but first check for svn by typing svn at the command prompt, if it returns command not found, then you will need to install svn. If you get positive output from svn, then type

svn checkout svn://svn.reactos.org/reactos/trunk/ /home/RosBuild/source/

Now your source folder will be populated with the latest source code (you may wish to make a note of the revision number).

Note: It is the same command to update your local source folder.

Compiling

Start RosBE and at the terminal/command prompt (bash-4.2#) 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



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

This is a 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, but please read this section first.

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:
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 hotkey 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:

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 [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 [Note], then press the hotkey combination of Tab+k on your keyboard, then type set condition * first always at the command prompt and press enter on the keyboard, then type cont [6] and press enter on the keyboard. Setting the condition to first always, 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: 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.

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:

Do not use Tab+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 - 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 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 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 [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 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.

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 [1] or on the Issues link on the navigation bar [2].

Click the Search for issues, which will take you to the Search [3] window.

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 [10] at the bottom of all the Comments, which opens the Comment editor [11]. 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.

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 [4], which will open a Create Issue form [5], when the form appears, there are just 2 input boxes to fill in (leave the others alone).

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.

Go to ReatOS JIRA and log in. Then go to the Issues [6] button and select Reported by Me [7] and your Issues will be shown.

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 [9].

Or further down at Attachments, you can use the Browse link or drag and drop files into Attachments to upload it [9]. 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.

If you only want to add more information, or to reply to a question from a developer, use the Comment button [10] 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 [11] to attach it to the report.

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 [8], move your mouse pointer over the title and a pencil will appear at the end [12], 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.


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 [13], where you can make your comments. When you have finished, just click on the Add button.

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.




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 revision that is half way between the two revisions, then 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 ' good ' revision and the last ' bad ' revision, until you have reached the point where they are next to each other, for example: *****5 (good) and *****6 (bad).



A layman's guide - log2lines.

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-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


Explanation:

D:\DebugWork\RosBE> .............................. The RosBE command prompt (which shows the directory of RosBE).

log2lines -m -d ............................................ The command to start log2lines with two prefixes.

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

D:\DebugWork\bootcd-66048-dbg.iso ...... The iso's directory path and name.

<D:\DebugWork\explorer-66048.log> ....... The debug log's directory path and name (you must include < at the front and > at the back).

D:\DebugWork\explorer-66048-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\bootcd-66048-dbg.iso <D:\DebugWork\explorer-66048.log> D:\DebugWork\explorer-66048-new.log


log2lines - Screenshots


log2lines - Unix subsection

When you install RosBE-Unix, there is no log2lines in the /RosBE/bin folder, like there is in a Windows install of RosBE, but, if or when you compile the ReactOS source, you will then find log2lines in /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 higher up this page, for instructions on how to install RosBE-Unix.

The log2lines command is in this format: log2lines switches ISO <old log> new log

Explanation:

log2lines .. Executes log2lines.

switches .. -m Marks the translated line with an * 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 log that you got for the bug.

new log .... This is the location and name for the modified log. It will be written with that name and at that location.

See also the explanation in the main section above.

Start RosBE and at the command prompt, type either of the examples.

Example 1:

/home/RosBuild/compiled/reactos/host-tools/log2lines -m -d /mnt/sda1/ReactOSDevelopment/debug-logs/bootcd-75458-dbg.iso </mnt/sda1/ReactOSDevelopment/debug-logs/SteamError2.log> /mnt/sda1/ReactOSDevelopment/debug-logs/SteamError2-new.log

Example 2 (change directory to the /host-tools folder):

cd /home/RosBuild/compiled/reactos/host-tools

./log2lines -m -d /mnt/sda1/ReactOSDevelopment/debug-logs/bootcd-75458-dbg.iso </mnt/sda1/ReactOSDevelopment/debug-logs/SteamError2.log> /mnt/sda1/ReactOSDevelopment/debug-logs/SteamError2-new.log



Revised and updated March 2017.

Minor text additions and the addition of some Unix subsections - August 2017.


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