!Help for Harinezumi  v0.07
====================


FIRST OF ALL, PLEASE NOTE WELL
------------------------------

This software is currently classed as "alpha test". That means "it
works on my machine" and YOU, dear reader, are a guinea pig.

This software should work, more or less as described. However in slim
chances it may crash, freeze your computer, translate your precious
files into misdrawn kanji, abort reality, or trigger a thermonuclear
war due to an unresolved bout of game playing. You accept that, as
alpha test software, these possibilities are real and probable and may
occur to you. If you are happy to nuke Nowheresville and end up staring
into the void of nothingness as reality comes crashing down around you,
then please try this software and provide feedback on how well it works,
or doesn't if that may be the case.



What is it?
-----------

Harinezumi, which is the Japanese word for "Hedgehog", is an attempt at making
a sanitised boot loader for RISC OS.

You see, the problem with the current system of boot scripts is that:
  1. If it fails, the boot sequence aborts and you will be dumped into the
     desktop (usually?) with a partially-completed boot sequence, which is
     often about as useful as a wireless access point is to a goldfish.
     
  2. Where did it fail? Why? This is usually something that would be determined
     using trial and error. This can be a real pain. Wouldn't it be nice if you
     could just look at a logfile and see where things don't look right?


      If you are running a RISC OS Ltd version of RISC OS, please refer
      to the note in the "Support" section, below.

     

How to install it - *NOT* RISC OS 5
-----------------------------------
[RISC OS 5 instructions below]

Open the !Boot.Utils directory, and copy "harinezumi" into there.

Open your !Boot.!Run file in your preferred editor.

It will look (more or less) like this:

  RMEnsure UtilityModule 3.10 Error This !Boot structure is only suitable ||
  for RISC OS 3.1 or later
  WimpSlot -min 64K
  Set Boot$Dir <Obey$Dir>
  /<Boot$Dir>.Utils.BootVars
  Set Boot$Path <Boot$Dir>.
  If "<Boot$State>" <> "desktop" then Obey -c <Boot$Dir>.Utils.BootRun else ||
  /<Boot$Dir>.Utils.DeskRun

  [where '||' means the line has been broken to fit here, but that and the
   following line are joined in the real file]
   
You see the final line, where it says "Obey -c <Boot$Dir>.Utils.BootRun"?
Simply replace that with "/<Boot$Dir>.Utils.harinezumi".
The file should now look like this:

  RMEnsure UtilityModule 3.10 Error This !Boot structure is only suitable ||
  for RISC OS 3.1 or later
  WimpSlot -min 64K
  Set Boot$Dir <Obey$Dir>
  /<Boot$Dir>.Utils.BootVars
  Set Boot$Path <Boot$Dir>.
  If "<Boot$State>" <> "desktop" then /<Boot$Dir>.Utils.harinezumi else ||
  /<Boot$Dir>.Utils.DeskRun

Save the updated file.

That's it.
You're all set.



How to install it - RISC OS 5
-----------------------------

This is slightly more complicated due to the fact that RISC OS 5's memory
allocation is a little different to older versions of RISC OS; which means
that IconSprites would fail (no memory for sprites), and numerous things would
be rejected due to not being able to move memory because an application is
running.


Open the !Boot.Utils directory, and copy "harinezumi" into there.

Then copy the file "harikick" into there as well.

Open your !Boot.!Run file in your preferred editor.

It will look (more or less) like this:

  RMEnsure UtilityModule 3.10 Error This !Boot structure is only suitable ||
  for RISC OS 3.1 or later
  WimpSlot -min 64K
  Set Boot$Dir <Obey$Dir>
  /<Boot$Dir>.Utils.BootVars
  Set Boot$Path <Boot$Dir>.
  If "<Boot$State>" <> "desktop" then Obey -c <Boot$Dir>.Utils.BootRun else ||
  /<Boot$Dir>.Utils.DeskRun

  [where '||' means the line has been broken to fit here, but that and the
   following line are joined in the real file]
   
You see the final line, where it says "Obey -c <Boot$Dir>.Utils.BootRun"?
Simply replace that with "Obey -c <Boot$Dir>.Utils.harikick".
The file should now look like this:

  RMEnsure UtilityModule 3.10 Error This !Boot structure is only suitable ||
  for RISC OS 3.1 or later
  WimpSlot -min 64K
  Set Boot$Dir <Obey$Dir>
  /<Boot$Dir>.Utils.BootVars
  Set Boot$Path <Boot$Dir>.
  If "<Boot$State>" <> "desktop" then Obey -c <Boot$Dir>.Utils.harikick else ||
  /<Boot$Dir>.Utils.DeskRun


NOTE: Here we run harikick, not harinezumi like the previous section says.
The harikick Obey file shifts some memory around and then runs Harinezumi.


Save the updated file.

That's it.
You're all set.



What will happen?
-----------------

RISC OS will boot as it normally does, although now there will be a bit
more rubbish on the screen, in pretty colours too. Don't worry about this
spewage, it is just Harinezumi reporting on what is happening.

If your boot drive has Write Access (as it normally would), you will
find the file !Boot.BootLog has been created. This is a log version of
the boot as was displayed on-screen. The primary difference is that the
log file contains result indications to help with diagnosis.

Here is a slightly contrived example:

  harinezumi v0.02*alpha* (2012/10/07) initialised
  ================================================

  Harinezumi built : 00:57:21, Oct  7 2012

  Boot started     : Sun,07 Oct 2012.00:57:53
  RISC OS version  : 5.19
  Memory available : 245760 bytes (240KiB).

  Okay: FX 247 2_10101010
  Okay: FX 229 1
  Okay: <Boot$Dir>.Library.apppath Run$Path <Boot$Dir>.Library.
  Okay: If Boot$OSVersion >= 300 then RMEnsure VProtect 2.37 RMLoad Boot:Utils.VProtect
  Okay: If Boot$OSVersion <  370 Then RMEnsure CallASWI   0.00 RMLoad Boot:Utils.CallASWI
  FAIL: If Boot$OSVersion >= 360 then RMEnsure AppPatcher 0.00 RMLoad Boot:Utils.PatchApp
  --->: [ File 'Boot:Utils.PatchApp' not found ]
  Okay: IfThere <Boot$Dir>.^.!Territory Then /<Boot$Dir>.^.!Territory
  Okay: If Boot$OSVersion >= 350 then WimpSlot -next 256K
  Okay: If Boot$OSVersion >= 350 then /Boot:Utils.FreePool
  FAIL: Obey -c <Boot$Dir>.Utils.SetChoices
  --->: [ File 'ADFS::BootDrive.$.!Boot.Utils.SetChoices' not found ]

  [and so on]


You can see that the good commands are prefixed with "Okay", while the
word "FAIL" in capitals indicates something went wrong. In this case,
the following line points to a copy of the error message to assist in
diagnosing what went wrong.


If you are looking at your screen as the computer boots, then the colours
are:
  Green   - this is good.
  Red     - something failed to load/start (you'll get one on RO5 as DeepKeys
            seems to be in the boot but it isn't 32 bit compatible!).
  Magenta - program error (may or may not be fatal).
  Cyan    - other messages are either white or cyan, usually not critical.



Customisation and options
-------------------------

Harinezumi offers two command line options.

The first is "-q". This switches Harinezumi to "quiet mode", where it will
tell you "RISC OS booting - xx%" and nothing else.
In quiet mode, program errors will be reported, but boot errors will NOT
be reported. The BootLog file will be the same as it always is, so may be
examined at your leisure.
Harinezumi will draw a cute little slidey-bar-thingy on the screen to
indicate how far along in the boot we are.

The second command line option is "-l" followed by a filename. This
permits you to override the default logfile location ($.!Boot.Logfile)
with one of your choosing.

For example:
  Harinezumi -q -l null:meh

This will switch Harinezumi to quiet mode and throw away the logfile,
which is not really advised... ;-)



Removing Harinezumi
-------------------

Simple. Just open the !Boot.!Run file and put back the command to run
the BootRun file; essentially just a reverse of the installation
procedure described above.



Support
-------

Officially, there isn't any.

Unofficially, email me and I'll see what I can do (or whinge on the
ROOL forum, I'm the dude with nearly 6000 posts so it's quite clear
that I have absolutely NO life whatsoever)...

...for any version of RISC OS *except* those created by RISC OS Ltd.

[this is because I am under the impression that some (all?) versions of
Select (and/or Adjust?) support multiple user profiles. I am not exactly
certain how this is implemented, suffice to say that it more than likely
alters the boot process in a way that Harinezumi may not work alongside.
If RISC OS Ltd are willing to "loan" me a copy of an emulator for an x86
machine plus a version of RISC OS that supports multiple user profiles,
then I'd look to supporting this behaviour. Until then...]


If you are reporting a program fault, please first visit the website at
http://www.heyrick.co.uk/software/harinezumi/ to check that you are using
the LATEST version.
If you are, please then report the problem with as much detail as possible
(hint, "harinezumi -v" will report version information and then exit).



Contact info
------------

Website:  http://www.heyrick.co.uk/software/harinezumi

          It helps to remember Japanese is usually pairs of letters
          arranged as consonant-vowel; hence ha-ri-ne-zu-mi. (^_^)

Email  :  heyrick1973 -at- yahoo -dot- co -dot- uk



Boring licence stuff
--------------------

This software is copyright  2017 Rick Murray.

It is released under the CDDL (version 1.0 only) licence. The source
is on my personal server. Ask nicely, or poke around the ROOL forum
where I've given a link to it. ;-)



Why Harinezumi, for goodness sake!?
-----------------------------------

I was going to give this product a boring name like "bootproc" or such;
but as I opened the editor to begin coding, my MP3 player started to
play "Harinezumi" by Hitomi Azuma. It's the opening theme to the anim
series "Fractale" (2011). You can watch the opening sequence here:
  http://www.youtube.com/watch?v=MMoRrvAeCjA
I then noticed the name was ten characters, the length of a traditional
RISC OS filename so I typed in into the editor in the top line and...
...today, Harinezumi is the name of this software!
