RockboxUtilityDevelopment < Main

Downloads
release
dev builds
extras
themes
Documentation
manual
wiki
device status
Support
forums
mailing lists
IRC
Development
bugs
patches
dev guide
Donate
Wiki > Main > RockboxUtility > RockboxUtilityDevelopment
---+!! Development of Rockbox Utility

%TOC%

---

---++ Tasks

[[http://www.rockbox.org/tracker/index.php?project=1&cat%5B%5D=37&status%5B%5D=open&do=index][Open Tasks in the tracker]]

---+++!! Milestone 1: be on par with the old wx version

%TABLE{ sort="off" headerbg="#99cccc" databg="#c6d6f5,#d6e6f5" tablerules="none" cellspacing="2" }%
| *What?* | *Status?* |
| Device detection | %Y% sansapatcher detection untested |
| Rockbox installation | %Y% done |
| Bootloader installation | %Y% done, needs testing |
| Font installation | %Y% done |
| Doom files installation | %Y% done |
| Theme installation | %Y% done |
| Talk file generation | %Y% done (only basic functionality) |
| Voice file installation | %Y% done |
| Uninstallation | %Y% done |
| Manual view | %Y% done: downloading to the device (no destination selection) |
| Complete Installation | %Y% done, code could be improved |
| Small Installation | %Y% done, code could be improved |
| Portable installation | %Y% done (only working if built as static binary) |
| Proxy setup | %Y% system proxy only working on linux (http_proxy environment variable) |
| Download cache | %Y% needs testing |
| !I18N | %Y% support added, translations missing |

---+++!! Milestone 2: further enhancements

%TABLE{ sort="off" headerbg="#99cccc" databg="#c6d6f5,#d6e6f5" tablerules="none" cellspacing="2" }%
| *What?* | *Status?* |
| uninstallation / install info | %Y% done |
| 1st installation detection | %Y% if no / no valid user configuration is found, display a warning and open the configuration dialog |
| Device detection | %Y% use USB PIDs for detection %Y% linux (using libusb), %Y% windows (setupapi based) |
| Proxy | %Y% support "system proxy" setting on windows (registry values used) |
| !L10N support | %Y% we have !I18N already, extend it to do real !L10N |
| Mountpoint resolving on mac | %Y% done |
| backup of installation prior to installing | %Y% rbutil now asks if you want to backup before installing a new Build |
| improving screenreader support | %Y% maybe add a drop downmenü with all install/uninstall options from the main tabs. / %Y% findout why jaws and other screenreaders have problems reading titles of QTabwidget: Qt bug, fixed with Qt 4.4.0. |
| builtin rbspeex and sapi.vbs | %Y% The rbspeex encoder should be built in, and the Sapi.vbs should be in the resource file (windows) |
| Talk file generation | support %Y% festival and the %Y% sapi scripts from svn; %Y% autodetect binaries; %Y% find a way to not make the progress window flicker; %Y% add option to generate talk files for directories only; %Y% incorporate sapi vbs scripts; %Y% add option to only voice certain file types; %X% add options to correct voicestrings |
| voice file creation | %Y% needs the servers to provide the features file for every player |
| Unsupported iPod | %Y% Display exactly which unsupported iPod was found so as to help avoid user confusion when they are e.g. sure they have a Video not Classic and think it is RBUtil that is wrong |
| General | Code clean up - being worked on. |
| Better Progress Window | console version needs implementation, Logging to a file  |
| Console commandos for rbutil | needs implementation - in Work ([[http://www.rockbox.org/tracker/task/8571][FS#8571]]) |
| clean orphan files | could be done by automatically performing an uninstallation before updating |
| install info cleanup | possibility to wipe all files that are marked as outdated in the info window / all files that don't match a specific (read: the current) version) |
| 1st time installation | Operate in wizard mode instead of the "invalid configuration" splash. First thing should be UI language selection, without needing to restart. |
| Device detection | Auto detection should probably display directly what was found; at least the highlighting should be more prominent (currently very faint on laptop LCD) |
| Accessibility | Accessibility in rbutil needs improvement. Most of those isses are Qt issues. - ([[http://www.rockbox.org/tracker/task/10205][FS#10205]]) |
---+++!! Milestone 3: additions / ideas

Some of the following could be implemented with plugins. -- Qt supports plugins, but it hasn't figured out how to make use of that. Its also unclear which functionality should go into plugins.

%TABLE{ sort="off" headerbg="#99cccc" databg="#c6d6f5,#d6e6f5" tablerules="none" cellspacing="2" }%
| *What?* | *How?* | *Status?* |
| Scrobbler submission | basically a frontend for libscrobbler | |
| tagnavi_custom.config generator | | |
| default configuration | provide some reasonable defaults for config.cfg | |
| video conversion | do it like !WinFF | |
| local repository | do we really want such a function? Offline mode does something similar | |
| Configfile editor | A Editor for Rockbox config files | |
| Optional components | Rbutil could install the midi patchset, if the license allows it (otherwise the patchset needs to be removed from the wiki as well) | |
| Install/ uninstall | Support for multiple devices would be nice (perhaps use some sort of (quasi-)unique device ID?) | |
| Translation | <strike>Support for editing .lang files in a user friendly way</strike><br/>There's an online tool available at http://themes.rockbox.org so having support for this in Rockbox Utility would only duplicate work | |
| UI Rework | see below | |
| Talkfile generation for database | | |

---+++ UI Rework
As rbutil gets more and more functions, the UI needs a rework. Lets collect ideas for a Rework here:

   * Mainscreen:
Combine the first three Tabs (Quickstart, Installation, Extras) into one. Make a more global selection of release or current Build. Screenshots of mockups by bluebrother:

[[http://www.alice-dsl.net/dominik.riebeling/rockbox/rbutil-mainwindow-idea.jpg][mainscreen]]

[[http://www.alice-dsl.net/dominik.riebeling/rockbox/rbutil-mainwindow-idea1.jpg][mainscreen during installation]]

Show more info about the currently selected Device. Ie currently installed version and maybe a player picture.
---

---++ How To Compile
If you want to work on RockboxUtility clone the [[http://git.rockbox.org/?p=rockbox.git;a=summary][rockbox.git]] repository. RockboxUtility lives in the subfolder ==rbutil/rbutilqt==. You can also use the script ==utils/common/deploy-rbutil.py== for building or creating a source tarball, however, this is intended for building releases and not suited if you intend to develop on RockboxUtility.

---

You have to have Qt Version 4.5.0 or higher installed. Since r22624 out-of-tree building is possible. You can still build in-tree.
   * building out-of-tree:<br />Create a build folder somewhere outside of the source tree and change to that. The recommended location for the build folder is in the rockbox source folder. Then you run the command ==qmake <path/to/rbutilqt.pro>== followed by ==make== in the build folder.
   * building in-tree:<br />change to the sources folder rbutilqt, run ==qmake==, then ==make==.
Depending on your installation the qmake binary of Qt4 might be called ==qmake-qt4==. On Linux you also need libusb1 (including the development headers). Alternatively you can build with libusb0 by appending ==-config libusb0== to the ==qmake== call.

*Notes:*
   * The *complete* path to the sources and build folders *must not contain spaces*!
   * The build defaults to a release build which has debugging output (even the console) disabled. To create a debug build run qmake with the config option "dbg", i.e. the following way: ==qmake -config dbg==
   * you can make the build output much more silent by adding the configuration "silent". The easier way is to add ==-config silent== to the qmake call (you can add multiple ==-config== switches, in case you also want to enable debugging output), or add the line ==CONFIG += silent== to the project file. 
      * *Important note on Windows* 
         * The "silent" feature is undocumented and might not work properly. Some versions of Qt are known to generate wrong path delimiters if used.
         * make sure to call the mingw32 make, not the msys one. You usually can ensure this by explicitly calling ==mingw32-make== instead of ==make==.
         * if you don't have Qt in your PATH (i.e. calling qmake.exe using a full path) make sure to use /'s in the path. Otherwise make will fail.
   * There is now a Makefile target "install" on non-windows platforms. This will only install the binary (to /usr/local/bin), language files are not handled yet. Unless you want to use translations you don't need to install anything else from the build. Translation files are now bundeled in the binary for non-debug builds.
   * The non-debug builds now include the translations (*.qm files) in a resource file. These files are not present when building for the first time, therefore ==qmake== will produce a warning. You can either safely ignore this warning (the translations are generated during the build process) or run ==lrelease rbutilqt.pro== before calling ==qmake== (==lrelease== might be called ==lrelease-qt4==, similar as ==qmake== mentioned above).

---+++!! Compiling on Windows
   * You need to install the following 
      * [[http://www.mingw.org][MinGW]]. If you install the Qt SDK you can use the bundled MinGW.
      * [[http://www.mingw.org/msys.shtml][msys]]. Get the installer (current is 1.0.11). Several parts built as libraries require some tools that are not part of !MinGW. As with !MinGW, append the ==bin== folder to your PATH. Make sure the !MinGW path comes first or use ==mingw32-make== instead of ==make== (msys' ==make== won't accepts backslashes in paths, but this is unfortunately needed by Qt).
      * get the "Qt Libraries for Windows package of [[http://qt-project.org][Qt]]. Optionally, get Qt Creator if you want to use it. If you want to use Qt Creator try to build on the command line first to ensure your Qt setup itself is working.
      * You don't need to put Qt's bin folder in the PATH variable. If you chose to not add it you need to copy the Qt libs to the same folder as the binary (of course this does not apply if you're building a static binary).
      * Building using Visual Studio isn't officially supported -- RockboxUtility uses some C99 features VS doesn't implement. See ==msvc/README== on how to build using Visual Studio. *Note:* There are additional bugs when building with MSVC, don't expect it to be fully functional.
      * The current binaries are built using the following configuration of Qt:%BR% ==configure -no-exceptions -static -release -no-webkit -no-dbus -no-phonon -no-phonon-backend -no-qt3support -no-opengl -no-direct3d -no-style-motif -no-style-cde==

---+++!! Compiling on Mac OS X
   * Install Qt (the "Qt Libraries" package is sufficient if you're not interested in Qt Creator or want to install it separately). Use the "Carbon" libraries to build for 10.4+. The "Cocoa" libraries require adding ==-config intel== to the ==qmake== call, disabling PPC support and making it 10.6+ only.
   * run =qmake=, then =make=. *Important note*: on OS X 10.6 the default compiler is gcc-4.2 which doesn't support the 10.4 SDK anymore. To make it use the older gcc-4.0 (part of Xcode 3.2) set =QMAKESPEC= explicitly, i.e. invoke qmake as =QMAKESPEC=macx-g++40 qmake=. Official support for OS X 10.6 also requires at least Qt 4.6.

---+++!! Statically Compiling on Linux

For building the static binary the following configuration was used:%BR% ==./configure -prefix /usr/local/qt4.4.3-static/ -release -static -no-exceptions -no-qt3support -no-phonon -no-phonon-backend -no-xinerama -no-openssl -no-xcursor -no-cups== %BR% You can have two differently configured versions of Qt alongside without any problems, just remember to call the correct qmake. There is no need to make the Qt bin-folder part of the PATH variable. If you want to omit demos and examples during Qt compilation, omit the ==-fast== option in the configure line and run ==make sub-src sub-tools== instead of ==make==.

---

---++ How to Translate

   * *Note:* Prebuilt binaries of Qt Linguist (without any dependencies) are available at http://code.google.com/p/qtlinguistdownload/

Qt supports !I18N and Rockbox Utility uses this. To translate Rockbox Utility do the following:
   * add a new file to the TRANSLATIONS line in =rbutilqt/rbutilqt.pro=.
   * run =lupdate rbutilqt.pro=
   * edit the resulting =*.ts= file using "linguist"
   * run =lrelease= to convert the =*.ts= file to the =*.qm= format that is used for !I18N.
   * put the resulting =*.qm= file in the same folder as the executable. Rockbox Utility will then detect the new translation and allow you to use it.
   * or add the resulting =*.qm= file in rbutil-lang.qrc and the language file will be built into the binary.
   * and don't forget to post the =*.ts= file to the tracker so we can include it ;-)

---+++ Translation status
*Note:* this table is generated using the script =langstats.py= and updated in the wiki manually. Do not edit the table manually, such changes will get lost on the next update with the script.
%TABLE{ sort="off" headerbg="#99cccc" databg="#c6d6f5,#d6e6f5" tablerules="none" cellspacing="2" }% 
|  *Translation status as of revision c1a71ab (2012-04-28 21:46:33 +0200)*  ||||||||
| *Language* | *Language Code* | *Translations* | *Finished* | *Unfinished* | *Untranslated* | *Updated* | *Done* |
| Czech | cs | 530 | 457 | 73 | 138 | 2012-02-23 22:48:53 +0100 | %ORANGE% 79%%ENDCOLOR% #######+   |
| German | de | 660 | 486 | 174 | 8 | 2012-02-23 23:08:41 +0100 | %GREEN% 98%%ENDCOLOR% #########+ |
| Finnish | fi | 300 | 239 | 61 | 368 | 2012-02-23 22:48:53 +0100 | %RED% 44%%ENDCOLOR% ####       |
| French | fr | 615 | 564 | 51 | 53 | 2012-02-24 21:47:40 +0100 | %GREEN% 92%%ENDCOLOR% #########  |
| Greek | gr | 434 | 363 | 71 | 234 | 2012-02-23 22:48:53 +0100 | %ORANGE% 64%%ENDCOLOR% ######     |
| Hebrew | he | 575 | 538 | 37 | 93 | 2012-02-23 22:48:53 +0100 | %ORANGE% 86%%ENDCOLOR% ########+  |
| Italian | it | 470 | 401 | 69 | 198 | 2012-02-23 22:48:53 +0100 | %ORANGE% 70%%ENDCOLOR% #######    |
| Japanese | ja | 578 | 541 | 37 | 90 | 2012-02-23 22:48:53 +0100 | %ORANGE% 86%%ENDCOLOR% ########+  |
| Dutch | nl | 625 | 450 | 175 | 43 | 2012-02-23 22:48:53 +0100 | %GREEN% 93%%ENDCOLOR% #########  |
| Polish | pl | 614 | 588 | 26 | 54 | 2012-02-23 22:48:53 +0100 | %GREEN% 91%%ENDCOLOR% #########  |
| Portuguese | pt | 433 | 363 | 70 | 235 | 2012-02-23 22:48:53 +0100 | %ORANGE% 64%%ENDCOLOR% ######     |
| Portuguese (Brasileiro) | pt_BR | 598 | 571 | 27 | 71 | 2012-02-23 22:48:53 +0100 | %ORANGE% 89%%ENDCOLOR% ########+  |
| Russian | ru | 624 | 600 | 24 | 44 | 2012-02-23 22:48:53 +0100 | %GREEN% 93%%ENDCOLOR% #########  |
| Turkish | tr | 223 | 167 | 56 | 445 | 2012-02-23 22:48:53 +0100 | %RED% 33%%ENDCOLOR% ###        |
| Chinese | zh_CN | 199 | 148 | 51 | 469 | 2012-02-23 22:48:53 +0100 | %RED% 29%%ENDCOLOR% ##+        |
| Chinese (trad) | zh_TW | 199 | 148 | 51 | 469 | 2012-02-23 22:48:53 +0100 | %RED% 29%%ENDCOLOR% ##+        |
---

---++ How to add a new Target

To add a new target you have to edit the following files:
   * rbutil/rbutilqt/rbutil.ini - add a new target similar to whats already there.
If your Target has a new Bootloader installation method: 
   * rbutil/rbutilqt/base/bootloaderinstallXYZ.cpp / h - add a new class which implements the virtual classes of !BootloaderInstallBase (at least install and uninstall) and does the necessary things for your bootloader. Don't forget to add those files to rbutil/rbutilqt/rbutilqt.pri to have them compiling with rbutil
   * rbutil/rbutilqt/base/bootloaderinstallbase.cpp - createBootloaderInstaller : add a case for your new Bootloaderclass
   * OF patcher program is going in a new mkXYZboot directory. Don't forget to edit rbutil/rbutilqt/rbutilqt.pro to have it included as a library (look for how other methods have been added)
   * base/bootloaderinstallBase.cpp : postinstallHints() if your target needs user info after bootloader installation, add it here.
If there are ways for your target to detect the mountpoint or, in case of duplicate USB-IDs, detect the correct Target: 
   * rbutil/rbutilqt/base/autodetection.cpp/h - edit so it also detects your specific files/folders or calls your specific detection method.

---

---++ How to add a new TTS Engine

The TTS Engines are in base/tts.cpp / .h. Add your new Engine to the list in initTTSList() and the switch in getTTS().

If your new engine is a simple external executable, you can add a template line to constructor of TTSExes and you are done.

If you have to interface your TTS Engine via another way, or want to give more options to the user, you have to create a new TTS Class which inherits from TTSBase. You will have to implement at least the following functions:
   * voice - generate a wavfile out of the given parameters
   * start - startup your engine
   * stop - stop your engine
   * configOk() - should return true, when everything setting is correct.
   * generateSettings() - generate settings-objects for your settings for display
   * saveSettings() - save the generated settings-objects to permanent storage.
To display settings, the TTS Classes implements the !EncTtsSettingInterface which you can find in base/encttssettings.h/cpp. In the generateSetting() function you should create !EncTtsSetting objects for all your settings. Each Setting contains the following Information: 
   * The type of the Setting (bool,double,int,string,readonlystring,stringlist)
   * The name of the Setting
   * The current value
   * If it is a stringlist, the list of strings
   * If it is a int or double, the min and max values
   * If the setting needs a refresh or browse button
You can connect to the following signals: 
   * refresh() - if you want to be noticed if the user clicks the refresh button.
   * dataChanged() - if you want to be noticed when ever the data changes
Add your newly generated objects with insertSetting() to the internal list. insertSetting() also takes a ID, which you can use to retrieve the object again in the saveSettings object.

---

---++ Distribution packages
Currently there are no distribution packages planned. Packages might be requested from distributions. Requests we are aware of: 
   * Ubuntu: https://bugs.launchpad.net/ubuntu/+bug/192989
   * !PCLinuxOS: http://www.pclinuxos.com/index.php?option=com_smf&Itemid=58&topic=61708.0
   * Arch Linux: http://aur.archlinux.org/packages.php?ID=26563
%X% Please note that we do *not* support any versions of Rockbox Utility packaged by distributions! 
---

---++ Autodetection

All supported devices can be detected automatically. Rockbox Utility will display a warning when autodetection wasn't successful; you can always select your device manually. If you installed Rockbox once it can get detected via the file /.rockbox/rockbox-info.txt. This will work on all devices. See DeviceDetection for further details.

---

---++ Resolving mountpoints
This relies on detecting the player first (see paragraph above). The following table list when / how we can resolve the mountpoint afterwards. This table only holds supported players; all supported player can now (as of 2008-04-03) be detected reliably. %X% denotes a possible way of resolving that hasn't been implemented yet. Once Rockbox is installed mountpoint resolving using rockbox-info.txt will always work. 
%TABLE{ sort="off" headerbg="#99cccc" databg="#c6d6f5,#d6e6f5" tablerules="none" cellspacing="2" }% 
| *Brand* | *Player* | *Windows* | *Linux* | *OS X* |
| Apple | all Ipods | %Y% resolving from drive UNC path figured by ipodpatcher (fallback: check for iPod_Control folder) | %Y% device node known by ipodpatcher, resolving using mtab | %Y% same as linux |
| Archos | all | %Y% detect some specific files (firmware image on disk, magic in firmware file) | %Y% same | %Y% same |
| Cowon | X5, M5 | %ICON{choice-no}% unknown (no specific file to check for) | %ICON{choice-no}% same | %ICON{choice-no}% same |
| Iriver | H100, H300 | %ICON{choice-no}% only detection based on USB possible, currently there is no way known to resolve USB PID -&gt; mountpoint | %ICON{choice-no}% same | %ICON{choice-no}% same |
| Iriver | H10 | %X% possible recognizing the bootloader file location | %X% same | %X% same |
| Packard Bell | Vibe 500 | %X% possible recognizing the bootloader file location | %X% same | %X% same |
| Sandisk | e200, c200 | %Y% resolving from drive UNC path figured by sansapatcher | %Y% device node known by sansapatcher, resolving using mtab | %Y% same as linux  |
| Olympus | m:robe 100 | %X% possible looking for bootloader file | %X% same | %X% same |
| Toshiba | Gigabeat | %X% possible searching for bootloader file | %X% same | %X% same |
---
---++ Releasing
The script =deploy-release.py= is intended to automate releasing by building the current checkout state and packaging it to a =tar.bz2= / =zip= file. Use the command line option =-q= / =--qmake= to pass the path to the qmake binary of the Qt installation you want to use (if there are multiple), otherwise the system is searched for a Qt4 installation and the first found gets used.

Brief release checklist
   1 update the version info in =version.h= and =Info.plist= and commit them.
   1 tag svn. As rbutil now needs parts of the main Rockbox sources we need to tag trunk, not only the rbutil folder. Use a version number as in the following example:<br /> =svn copy svn://svn.rockbox.org/rockbox/trunk svn://svn.rockbox.org/rockbox/tags/rbutil_1.0.5=
   1 run =deploy-release.py= to do the following steps. Don't forget to =-a libusb.a= on the platforms that require it.
      1 <strike>lrelease the language files (they are now in the resource, so this need to be done before building!)</strike> make takes care of this now.
      1 configure with =qmake -config release -config static=
      1 build against static libraries ;-)
      1 linux: strip the binaries (seems to be mostly an issue on linux)
      1 windows: upx the binary to cut down its size
      1 osx: run osx_deploy.sh. Make sure libusb is static and universal.
      1 compress the result (tarball / zip)
   1 Put the result to some public location and ping someone with access to the download server

---+++ deploy-release.py
The script =deploy-release.py= is intended for simplifying the release process but can also get used for building. This is especially useful if you just want to build RockboxUtility and don't want to get the full Rockbox svn. 
   * Prerequisites 
      * all prerequisites for building Rockbox Utility itself
      * Python. Tested with Python 2.5 and 2.6. Will not work with Python 3.0
      * [[http://pysvn.tigris.org/][pysvn]]
      * [[http://code.google.com/p/which/][which.py]]
      * [[http://upx.sourceforge.net/][upx.exe]] (Windows only)
   * Features 
      * Download sources from SVN trunk (default) or tag (as specified on command line) or build from local tree (as specified)
      * Create source archive (.tar.bz2)
      * Build binary archive (.tar.bz2 on Linux, .zip on Windows)
      * Support building static and dynamically linked binaries
   * Usage 
      * Use =deploy-release.py -h= to get an overview of the supported command line options. All created archives will get placed in the current directory while building itself takes place in the systems temporary path.
      * *Note:* already existing archives will get overwritten without notice!

---

---++ History
This is the Qt version of Rockbox Utility. It supersedes the [[RockboxUtilityOld][older wxwidgets based version]] which isn't maintained anymore and has therefore been removed from svn.

---
r94 - 28 Oct 2012 - 17:51:00 - DominikRiebeling
Parents: RockboxUtility