Make sure codec directory exists before creating link file.

[kugel-rb.git] / manual / getting_started / installation.tex

% $Id$ %
\chapter{Installation}\label{sec:installation}

\opt{ipodnano}{
  \note{Rockbox presently runs only on the original Ipod Nano. Rockbox does
  \emph{not} run on the second, third, or fourth generation Ipod Nano.
  For information on identifying which Ipod you own, see this page on
  Apple's website: \url{http://www.info.apple.com/kbnum/n61688}.
  }
}
\opt{ipodvideo}{
  \note{Rockbox presently runs only on the 5th and 5.5th generation Ipod videos.
  Rockbox does \emph{not} run on the newer, 6th/Classic generation Ipod. 
  For information on identifying which Ipod you own, see this page on Apple's 
  website: \url{http://www.info.apple.com/kbnum/n61688}.
  }
}
\opt{e200,c200}{
  \note{Rockbox doesn't function on the newer v2 models.  They can be identified
  by checking the Sandisk firmware version number under 
  Settings $\rightarrow$ Info.  The v1
  firmware is named 01.xx.xx, while the v2 firmware begins with 03.}
}

\section{Overview}
There are two ways of installing Rockbox: automated and manual. While the
manual way is older, more tested and proven to work correctly, the
automated installation is based on a nice graphical application that does
almost everything for you. It is still important that you have
an overview of the installation process to be able to select the correct
installation options.

\opt{MASCODEC}{Rockbox itself comes as a single package. There is no need
  to install additional software for running Rockbox.}
\opt{swcodec} {
  \opt{HAVE_RB_BL_ON_DISK}{There are three separate components,
    two of which need to be installed in order to run Rockbox:}
  \opt{HAVE_RB_BL_IN_FLASH}{There are two separate components
    which need to be installed in order to run Rockbox:}

\begin{description}
\opt{HAVE_RB_BL_ON_DISK}{
\item[The \playerman{} bootloader.]
  The \playerman{} bootloader is the program that tells your \dap{} how to load
  and start the original firmware. It is also responsible for any emergency,
  recovery, or disk modes on your \dap{}.  This bootloader is stored in special flash
  memory in your \playerman{} and comes factory-installed. It is not necessary
  to modify this in order to install Rockbox.}

\item[The Rockbox bootloader.] \index{Bootloader}
  \opt{HAVE_RB_BL_ON_DISK}{The Rockbox bootloader is loaded from disk by
  the \playerman{} bootloader. It is responsible for loading the Rockbox
  firmware and for providing the dual boot function. It directly replaces the
  \playerman{} firmware in the \daps{} boot sequence.
  \opt{gigabeatf}{\note{Dual boot does not currently work on the Gigabeat.}}}

  \opt{HAVE_RB_BL_IN_FLASH}{
  The bootloader is the program that tells your
  \dap{} how to load and start other components of Rockbox. This is the
  component of Rockbox that is installed to the flash memory of your
  \playerman.}

\item[The Rockbox firmware.]
  \opt{HAVE_RB_BL_IN_FLASH}{Unlike the \playerman{} firmware, which runs
  entirely from flash memory,}
  \opt{HAVE_RB_BL_ON_DISK}{Similar to the \playerman{} firmware,}
  most of the Rockbox code is contained in a
  ``build'' that resides on your \daps{} drive. This makes it easy to
  update Rockbox. The build consists of a directory called
  \fname{.rockbox} which contains all of the Rockbox files, and is 
  located in the root of your \daps{} drive.

\end{description}
}

\nopt{player} {
    Apart from the required parts there are some addons you might be interested
    in installing.
    \begin{description}
    \item[Fonts.] Rockbox can load custom fonts. The fonts are
        distributed as a separate package and thus need to be installed
        separately. They are not required to run Rockbox itself but
        a lot of themes require the fonts package to be installed.

    \item[Themes.] The view of Rockbox can be customized by themes. Depending
        on your taste you might want to install additional themes to change
        the look of Rockbox.
    \end{description}
}

\section{Prerequisites}\label{sec:prerequisites}
\index{Installation!Prerequisites}
Before installing Rockbox you should make sure you meet the prerequisites.
You may need some additional tools for installation. In most cases these will already be available on your computer, but if not, installing some additional
software might be necessary.

\begin{description}
\item[USB connection.] To transfer Rockbox to your \dap{} you need to
  connect it to your computer. For manual installation/uninstallation, or 
  should autodetection fail during automatic installation, you need to know 
  where to access the \dap{}. On Windows this means you need to figure out 
  the drive letter associated with the \dap{}. On Linux you need to know the 
  mount point of your \dap{}.

  \opt{ipod}{
    Your \dap{} should enter disk mode automatically when connected to a
    computer via USB. If your computer does not recognise your \dap{}, you may
    need to enter the disk mode manually. Disconnect your \dap{} from the
    computer. Hard reset the \dap{} by pressing and holding the \ButtonMenu{} and
    \ButtonSelect{} buttons simultaneously. As soon as the \dap{} resets, press
    and hold the \ButtonSelect{} and \ButtonPlay{} buttons simultaneously. Your
    \dap{} should enter disk mode and you can try reconnecting to the computer.
  }

  \opt{ipod3g,ipod4g,ipodcolor,ipodmini}{
    \note{\index{Firewire}Firewire detection is not supported in Rockbox at 
    the moment. Please use USB only.} 
  }
  \opt{x5}{
    \note{When instructed to connect/disconnect the USB cable, always use
    the USB port through the subpack, not the side 'USB Host' port! The side port
    is intended to be used for USB OTG connections only (digital cameras, memory
    sticks, etc)!}
  }    

  \opt{sansa}{\warn{The following steps require you to change the setting in
    \setting{Settings $\rightarrow$ USB Mode} to \setting{MSC} from within the
    original firmware. Never extract files to your \dap{} while it is in
    recovery mode.}}
  \opt{h10,h10_5gb}{\warn{The following steps require you to use UMS mode and so
    may require use of the UMS trick as described in the bootloader installation
    section.}}
  \opt{gigabeatf}{\warn{During installation, do not connect your \dap{}
    using the cradle but plug the USB cable directly to the \dap{}.}}  
\end{description}
For manual installation and customization additional software is required.
\begin{description}
\item[ZIP utility.]\index{zip}
  Rockbox is distributed as a compressed archive using the
  \fname{.zip} format. Your computer will normally already have a means of
  handling such archive files. Windows XP has built-in support for
  \fname{.zip} files and presents them to you as directories unless you
  have installed a third party program that handles compressed files. For
  other operating systems this may vary. If the \fname{.zip} file format
  is not recognised on your computer you can find a program to handle them
  at \url{http://www.info-zip.org/} or \url{http://sevenzip.sf.net/}, both of
  which can be downloaded and used free of charge.
\item[Text editor.] As you will see in the following chapters, Rockbox is
  highly configurable. In addition to saving configurations,
  Rockbox also allows you to create customised configuration files. If you
  would like to edit custom configuration files on your computer, you will
  need a text editor like Windows' ``Wordpad''.
\end{description}

\opt{ipod}{
  \note{In addition to the requirements described above, Rockbox only works on
  Ipods formatted with the FAT32 filesystem (i.e. Ipods initialized by Itunes
  for Windows). It does not work with the HFS+ filesystem (i.e. Ipods
  initialized by Itunes for the Mac). More information and instructions for
  converting an Ipod to FAT32 can be found on the
  \wikilink{IpodConversionToFAT32} wiki
  page on the Rockbox website.  Note that after conversion, you can still use
  a FAT32 Ipod on a Mac.
  }
}

\section{Installing Rockbox}\label{sec:installing_rockbox}\index{Installation}

\opt{ipodvideo}{\warn{There are separate versions of Rockbox for the 30GB and 
  60GB/80GB models.  You must ensure you download the correct version for your 
  \dap{}.}}

\subsection{Automated Installation}

\opt{mrobe100}

To automatically install Rockbox, download the official installer and
housekeeping tool \textsc{Rockbox Utility}. It allows you to:
\begin{itemize}
\item Automatically install all needed components for using Rockbox
        (``Small Installation'')
\item Automatically install all suggested components (``Full Installation'')
\item Selectively install optional components
\item Install additional themes
\item Install voice files and generate talk clips
\item Uninstall all components you installed using Rockbox Utility
\end{itemize}
Prebuilt binaries for Windows, Linux and MacOS~X are
available at the \wikilink{RockboxUtility} wiki page.
\\*
\warn{When first starting \textsc{Rockbox Utility} run ``Autodetect'', 
found in the configuration dialog (File $\rightarrow$ Configure). Autodetection
can detect most player types. If autodetection fails or is unable to detect 
the mountpoint, make sure to enter the correct values. The mountpoint indicates
the location of the \dap{} in your filesystem. On Windows, this is the drive
letter the \dap{} gets assigned, on other systems this is a path in the
filesystem.}

\opt{ipodvideo}
    {\warn{Autodetection is unable to distinguish between the
    \playerman{} 30~GB and 60~GB / 80~GB models and defaults to the
    30~GB model. This will usually work but you might want to check the
    detected value, especially if you experience problems with Rockbox.}
}

\note{Rockbox Utility currently lacks some guiding messages. Please have a
        look at the manual installation instructions if you are stuck
        during installation.}

\subsection{Manual Installation}

\subsubsection{Choosing a Rockbox version}\label{sec:choosing_version}

There are three different types of firmware binaries available from the
Rockbox website:
\label{Version}
Release version, current build and daily build. You need to decide which one
you want to install and get the appropriate version for your \dap{}.

\begin{description}

\item[Release.] The release version is the latest stable release, free
  of known critical bugs. The current stable release of Rockbox, version
  3.0, is available at \url{http://www.rockbox.org/download/}.
  
\item[Current Build.] The current build is built at each source code change to
  the Rockbox SVN repository and represents the current state of Rockbox
  development. This means that the build could contain bugs but most of
  the time is safe to use. You can download the current build from  
  \url{http://build.rockbox.org/}.

\item[Archived Build.] In addition to the release version and the current build,
  there is also an archive of daily builds available for download. These are
  built once a day from the latest source code in the SVN repository. You can
  download archived builds from \url{http://www.rockbox.org/daily.shtml}.

\end{description}

\warn{Because current builds and daily builds are development versions which 
      change frequently, they may behave differently than described in this manual, 
      or they may introduce new (and maybe annoying) bugs. If you do not want to 
      get undefined behaviour from your \dap{}, you should stick to the current 
      stable release if there is one for your \dap{}. If you want to help with 
      project development, you can try development builds and help by reporting bugs. 
      Just be aware that these are development builds that are highly functional 
      but not perfect!}

\subsubsection{Installing the firmware}\label{sec:installing_firmware}

\begin{enumerate}

\item Download your chosen version of Rockbox from the links in the
  previous section.

\item Connect your \dap{} to the computer via USB
  \opt{ipod3g,ipod4g,ipodmini,ipodcolor}{ or Firewire} as described in
  the manual that came with your \dap{}.

\item Take the \fname{.zip} file that you downloaded and use
 the ``Extract all'' command of your unzip program to extract 
 the files onto your \dap{}.

\note{The entire contents of the \fname{.zip} file should be extracted 
directly to the root of your \daps{} drive. Do not try to
create a separate directory on your \dap{} for the Rockbox
files! The \fname{.zip} file already contains the internal
structure that Rockbox needs.}

\end{enumerate}

\opt{archos}{
  \note{
    If the contents of the \fname{.zip} file are extracted correctly, you will
    have a file called \fname{\firmwarefilename} in the main directory of your
    \daps{} drive, and also a directory called \fname{.rockbox}, which contains a
    number of other directories and system files needed by Rockbox. If you receive a
     ``-1'' error when you start Rockbox, you have not extracted the contents of
    the \fname{.zip} file to the proper location.
  }
}

% This has nothing to do with swcodec, just that these players need our own
% bootloader so we can decide where we want the main binary.
\opt{swcodec}{
  \note{
    If the contents of the \fname{.zip} file are extracted correctly, you will
    have a directory called \fname{.rockbox}, which contains all the files needed
    by Rockbox, in the main directory of your \daps{} drive. If you receive a
    ``-1'' error when you start Rockbox, you have not extracted the contents of
    the \fname{.zip} file to the proper location.
  }
}

\nopt{player}{
  \subsubsection{Installing the fonts package}{\index{Installation!Fonts}\label{sec:installing_fonts}
    Rockbox has a fonts package that is available at
    \url{http://www.rockbox.org/daily.shtml} or from the \emph{extras} link in
    the menu on the Rockbox website. While the current builds and
    daily builds change frequently, the fonts package rarely changes and is
        therefore not included in these builds.  When installing Rockbox for the first
        time, you should install the fonts package. The release version, on the other hand,
        does not change, so fonts are included with it.

  \begin{enumerate}

  \item Download the fonts package from the link above.

  \item Take the file that you downloaded above, and use the ``Extract
    all'' command of your unzip program to extract the files in the
    \fname{.zip} file onto your \dap{}. As with the firmware installation, the
    entire contents of the fonts \fname{.zip} should be extracted directly to the
    root of your \daps{} drive. Do not try to create a separate directory
    on your \dap{} for the fonts! The \fname{.zip} already contains the
    correct internal structure.

  \end{enumerate}
  }
}

\opt{swcodec}{
  \subsubsection{Installing the bootloader}
  \opt{h1xx,h300}{\input{getting_started/iriver_install.tex}}
  \opt{ipod}{\input{getting_started/ipod_install.tex}}
  \opt{m5,x5}{\input{getting_started/iaudio_install.tex}}
  \opt{h10,h10_5gb}{\input{getting_started/h10_install.tex}}
  \opt{gigabeatf}{\input{getting_started/gigabeat_install.tex}}
  \opt{sansa}{\input{getting_started/sansa_install.tex}}
  \opt{mrobe100}{\input{getting_started/mrobe100_install.tex}}
  \opt{gigabeats}{\input{getting_started/gigabeats_install.tex}}
}

\subsection{Enabling Speech Support (optional)}\label{sec:enabling_speech_support}
\index{Speech}\index{Installation!Optional Steps}
If you wish to use speech support you will also need a voice file, English ones
are available from \url{http://www.rockbox.org/daily.shtml}. Download the
``voice'' package for your player and unzip it directly to the root of your \dap.
You should now find an \fname{english.voice} in the \fname{/.rockbox/langs}
directory on your \dap{}. Voice menus are enabled by default and will come
into effect after a reboot. See \reference{ref:Voiceconfiguration} for details
on voice settings.

\section{Running Rockbox}
Remove your \dap{} from the computer's USB port. %
\nopt{ipod,e200}{Unplug any connected power supply and turn the unit off. When
you next turn the unit on, Rockbox should load. }%
\opt{ipod}{Hard resetting the Ipod by holding
  \opt{IPOD_4G_PAD}{\ButtonMenu{}+\ButtonSelect{}}%
  \opt{IPOD_3G_PAD}{\ButtonMenu{}+\ButtonPlay{}}
  for a couple of seconds until the \dap{} resets. Now Rockbox should load.
} %
\opt{e200}{Your e200 will automatically reboot and Rockbox should load. }%
When you see the Rockbox splash screen, Rockbox is loaded and ready for
use.

\opt{ipod}{
  \note{
    If you have loaded music onto your \dap{} using Itunes, 
    you will not be able to see your music properly in the \setting{File Browser}. 
        This is because Itunes changes your files' names and hides them in 
        directories in the \fname{Ipod\_Control} directory. Files placed on your 
        \dap{} using Itunes can be viewed by initializing and using Rockbox's database.
        See \reference{ref:database} for more information.
  }
}

\section{Updating Rockbox}
Updating Rockbox is easy even if you do not use the Rockbox Utility.
Download a Rockbox build.
(The latest release of the Rockbox software will always be available from
\url{http://www.rockbox.org/download/}). Unzip the build to the root directory
of your \dap{} like you did in the installation stage. If your unzip
program asks you whether to overwrite files, choose the ``Yes to all'' option.
The new build will be installed over your current build.

\note{If you use Rockbox Utility be aware that it cannot detect manually
        installed components.}

\section{Uninstalling Rockbox}\index{Installation!uninstall}

\nopt{gigabeatf,m5,x5,archos,mrobe100}{
  \note{The Rockbox bootloader allows you to choose between Rockbox and 
  the original firmware. (See \reference{ref:Dualboot} for more information.)}
}

\subsection{Automatic Uninstallation}
You can uninstall Rockbox automatically by using Rockbox Utility. If you
installed Rockbox manually you can still use Rockbox Utility for uninstallation
but will not be able to do this selectively.

\opt{h1xx,h300}{\note{Rockbox Utility cannot uninstall the bootloader due to
the fact that it requires a flashing procedure. To uninstall the bootloader
completely follow the manual uninstallation instructions below.}}

\subsection{Manual Uninstallation}

\opt{archos}{
  If you would like to go back to using the original \playerman{} software,
  connect the \dap{} to your computer, and delete the
  \fname{\firmwarefilename} file.
}

\opt{h10,h10_5gb}{
  If you would like to go back to using the original \playerman{} software,
  connect the \dap{} to your computer, and delete the
  \opt{h10}{\fname{H10\_20GC.mi4}}\opt{h10_5gb}{\fname{H10.mi4}} file and rename
  \fname{OF.mi4} to \opt{h10}{\fname{H10\_20GC.mi4}}\opt{h10_5gb}{\fname{H10.mi4}}
  in the \fname{System} directory on your \playertype{}. As in the installation,
  it may be necessary to first put your device into UMS mode.
}

\opt{mrobe100}{
  If you would like to go back to using the original \playerman{} software,
  connect the \dap{} to your computer, and delete the
  \fname{pp5020.mi4} file and rename
  \fname{OF.mi4} to \fname{pp5020.mi4}
  in the \fname{System} directory on your \playertype{}.
}

\opt{e200}{
  If you would like to go back to using the original \playerman{} software,
  connect the \dap{} to your computer, and follow the instructions to install
  the bootloader, but when prompted by sansapatcher, enter \texttt{u} for uninstall,
  instead of \texttt{i} for install. As in the installation, it may be necessary to
  first put your device into MSC mode.
}

\optv{ipod}{
  To uninstall Rockbox and go back to using just the original Ipod software, connect
  the \dap{} to your computer and follow the instructions to install 
  the bootloader but, when prompted by ipodpatcher, enter \texttt{u} for uninstall 
  instead of \texttt{i} for install.
}

\opt{m5,x5}{
  If you would like to go back to using the original \playerman{} software,
  connect the \dap{} to your computer, download the original \playername{}
  firmware from the \playerman{} website, and copy it to the \fname{FIRMWARE}
  directory on your \playername{}. Turn off the \dap{}, remove the USB cable
  and insert the charger. The original firmware will automatically be flashed.
}

\opt{h1xx,h300}{
  \note{
    If you want to remove the Rockbox bootloader, simply flash an unpatched
    \playerman{} firmware. Be aware that doing so will also remove the bootloader
    USB mode. As that mode can come in quite handy (especially when
    having disk errors) it is recommended to keep the bootloader. It also
    gives you the possibility of trying Rockbox anytime later by simply
    installing the distribution files.
    \opt{h1xx}{
      The Rockbox bootloader will automatically start the original firmware if
      the \fname{.rockbox} directory has been deleted.
    }%
    \opt{h300}{%
      Although if you retain the Rockbox bootloader, you will need to hold the
      \ButtonRec{} button each time you want to start the original firmware.
    }
  }
}

If you wish to clean up your disk, you may also wish to delete the
\fname{.rockbox} directory and its contents.
\nopt{m5,x5}{Turn the \playerman{} off.
  Turn the \dap{} back on and the original \playerman{} software will load.
}