Database Tool

This is about the little tool hidden away behind the 'Build DB' link in Windows, or, as it's known on the other platforms, arcan_romman.rb.

This tool is a command-line controlled set of scripts that helps changing or generating the database in a safe-way, but also to try and reach a "zero config" approach for setting up and embedding most emulators into Arcan.

---

Basic Use

The prerequisites to using this tool is a ruby1.9 interpreter, and the gems/addons nokogiri and sqlite3.

./arcan_romman.rb command genericargs commandargs

where command can be:
builddb -- create a new database and populate with games.
list -- search for entries in the specified database
alterdb -- update, insert or delete entries
exec -- build the commandline for a game and launch it

so the most important command is builddb, and then the others can be used to verify and fix your configuration.

the genericargs are:
--dbname filename -- set the full path/filename for the output database
--rompath pathname -- point to the resources/games folder
--targetpath pathname -- point to the resources/targets folder

Depending on which importer scripts are installed (resourcepath/scripts/importers/.rb) the commandargs* will be populated with options that each script takes. The reason for the --targetpath is that some importer scripts (notably mame) need to run the target to extract metadata about the games it supports. Running the tool without any arguments should generate a full list of detected options.

In the list both on generic- arguments and importer-specific ones, you'll find those matching --genargs, --genintargs, --genextargs (similarly, --mameargs, --mameintargs, etc.).

The --???args are always used when launching a target, the --???intargs are added only when the target is launched in internal mode, and the ???extargs are added only when the target is launched in external mode.

There are also special strings you can add to the arguments you want,
[romset] -- expand to the name of the romset (filename) of the game being launched.
[romsetfull] -- expand to resourcepath/games/targetname/romsetname.
[gamepath] -- expand to resourcepath/games.
[themepath] -- expand to themepath/themename.

---

Building a Database

The most useful / common command is builddb.

By default, this is a destructive command, it will wipe your database unless you explicitly tell it not to with the --update command.

It will scan your resources/targets subfolder for valid targets (executables, and libretro- compatible shared libraries (.dll on windows, .so on BSD and Linuxes)

When a target has been found, it first asks all known importer scripts if it can handle the target in question and, if no importer can, use a generic fallback.

The matching importer will then be fed with the entries from the subfolder in resources/games with a matching subdirectory in games.

In addition to the specialized arguments that each importer accepts, there are a few arguments specific to the builddb command, these are:

--nogeneric (don't use the generic fallback at all)
--update (only add / update metadata, don't delete anything)
--skipgroup targetname (can be repeated, don't scan targetname)
--scangroup targetname (can be repeated, only scan targetname)

In addition, the generic fallback importer will probe libretro- cores for supported extensions to use as a filter, it will also try and map a few common target names (snes9x => Super Nintendo (SNES)) to system names for easier filtering.
Finally, It can be set to (--genscrape, --genscrapemedia) scan theGamesDB for additional metadata, and download screenshots, boxart etc.

---

Internals

(mainly for curious developers)

the arcan_romman.rb is just a simple wrapper that prints usage instructions, parses arguments and tries to locate the other scripts.

This is done by searching a few known paths (., ./scripts, ./resources/scripts, HOMEDIR/.arcan/resources/scripts, /usr/local/share/arcan/resources/scripts, /usr/share/arcan/resources/scripts ) for romman_base.rb

Afterwards, it scans the subdir to romman_base called importers for .rb files and loads all of them, checks the contained classes for a few methods (set_defaults, accepted_arguments, check_games, check_target).

the accepted arguments are added to the scanned arguments and the usage instructions.

look at generic.rb and mame.rb for examples of importers.