RAPPS

From ReactOS Wiki
Jump to: navigation, search

RAPPS, previously known as Download!, is a small program located in C:\ReactOS\System32 that allows users to download, install and update multiple programs without hassle.

It has its own application list that can be expanded by the user and the community. Applications that are included in the list by default are tested and most likely work on ReactOS.

How It Works

The official list of downloadable programs (an archive "rappmgr.cab" or "rappmgr2.cab"), is kept on a public ReactOS server and synced every time RAPPS is launched for the first time. Once the rappmgr.cab is downloaded to %appdata%\RApps, RAPPS extracts it using cabinet.dll inside %appdata%\RApps\appdb. After that, it will parse all the *.txt files contained therein.

Every subsequent time the program tries to access the local .txt files until a database update is manually triggered by the user.

If the rappmgr.cab file is moved or just missing, RAPPS will download it again.

Each program entry consists of a text file formatted with an INI-like syntax. Every .txt file describes a program, the filename is used as a unique identifier and should correspond to the software it "contains".

Submitting New Applications

It is possible to submit new application creating a txt file according to the file schema, forking the rapps-db repository on GitHub and sending your submission as a Pull-Request.

Before submitting the Pull Request, test the files by pasting the document in the \RApps\appdb folder and clicking "Refresh" in the GUI.

Description files need to be saved in UTF-16 LE (Little Endian) in the rapps folder on disk. Without this, characters out of the ANSI range will display broken mojibake, some editors like Notepad++ call this format UCS-2 Little Endian. Line endings must be set as Windows format (\r\n). At the end of the file, there must be one empty line.

If included in the ReactOS source code versioning entries are stored in UTF-8 without BOM (Byte Order Mask) for VCS friendliness. They get automatically converted to UTF-16 when creating the compressed rappmgr.cab package.

It is suggested that the commits to be squashed into one commit before a PR. If the reviewers asked for changes, ensure that the commits are squashed afterwards.

File Schema

Sections

RAPPS can show different programs' information accordingly to the host system language: to achieve this, the INI files used by RAPPS are divided in section.

Each section begins with [Section.XXXX], where XXXX is a four-digit Locale ID, that uniquely identifies a language. A list of Locale IDs can be found on Microsoft Docs (last four digits of the Language ID column). To avoid "colliding" codes (same ID used for multiple languages), also check MS-LCID Reference, for example in the 14.1 protocol revision (obsolete) see Language ID at page 9.

An exception is made for the default entry, that is only defined as [Section]: this should contain information in English.

If there is no entry for the host system language, the default entry is chosen. For example if the system is set to Spanish and there is no Spanish entry of a program, then software description etc. will be displayed in English.

Note that every field in a section can be customized for a language, not only the description (for example if a program offers different download links for different localizations). Fields that are not customized for a language will use the default entry in [Section].

Here is a minimal example of a multilanguage file:

[Section]
Name = My Program Name
Category = 16
URLDownload = https://example.com/MyProgram.exe

; Russian language
[Section.0419]
Name = Имя моей программы 
URLDownload = https://example.com/MyProgram_LocalizedRussian.exe

RAPPS also accepts neutral language codes, meaning that you can do things like this[1]:

; Default English fallback, used if everything else fails.
[Section]
Name = Name in English

; Neutral Spanish, used if the specific variant of Spanish does not match.
[Section.0a]
Name = Name in Generic Spanish

; Spanish from Spain, used if the system is configured for it.
[Section.0c0a]
Name = Name in Castilian Spanish

Note that is possible to create a file without an English entry, so that the program would be only shown to systems set to determinate languages, but it is discouraged, as users aren't able yet to choose the languages they want to visualize (so for example if a French-speaking user would set the system to English, RAPPS would not show eventual French-only entries, even if the user is potentially able to use them).

RAPPS behaviour on systems with multiple languages has not been documented yet.

Sections Fields

Here is an example description file.

[Section]
; Mandatory fields
Name = My fun stuff-o-matic
Category = 5
URLDownload = https://ftp.example.org/pub/installer.exe
SizeBytes = 10485760

; Optional fields in alphabetical order (no experimental features)
Description = Shortish description giving some additional background information about what it does.
Icon = SomeIcon.ico
License = GPL
RegName = Name in Registry
SHA1 = 47480394167aca4869b7bf330af6c6fc5ca4ac25
URLSite = https://example.org/
Version = 1.1.1

Let's analyze it from top to the bottom. The following fields are mandatory.

Name

This is the program name that is displayed.

Category

The category of the program. Category name corresponds to the number. Currently on ReactOS 0.4.13 there are 15 + 1 categories:

  • 1 – Audio: Software for recording, playing, modifying, converting sounds
  • 2 – Video: as above but applied to videos and movies
  • 3 – Graphics: a above, but applied to graphics and images
  • 4 – Games & Fun: games, console emulators etc.
  • 5 – Internet & Network: browsers, IM clients, FTP software, Remote desktop etc.
  • 6 – Office: office suites and similar
  • 7 – Development: IDEs, debuggers, compilers and anything related to software development
  • 8 – Edutainment: software related to education & teaching, like dictionaries and translators
  • 9 – Engineering: CAD, FEM, numerical computation etc.
  • 10 – Finance: balances management, warehouse software, trade monitors etc.
  • 11 – Science: programs for simulation, advanced calculus, chemistry, physics and similar
  • 12 – Tools: utilities like archiving software, disc burning utilities etc.
  • 13 – Drivers: device drivers
  • 14 – Libraries: libraries and runtimes, usually needed to run/develope other programs
  • 15 – Themes: themes for ReactOS or Windows
  • 16 – Other: programs that do not fit in above categories

URLDownload

Direct link to the installer/program. Scripted download are not supported yet, so ensure it is a direct link to a file. HTTPS is not mandatory but recommended.

The following fields are optional (but recommended).

Description

The description of the program giving some additional background information about what it does.

License

The license under which the software is released, for example Apache, GPL, MIT... Non-libre software is usually released under a End-User License Agreement (EULA) shipped with the software.

Icon

RAPPS supports 'per app' icons, that will be shown instead of the generic 'application' icon. The icon can be specified with the field name 'Icon', and include the .ico extension. The icon itself should be placed in the `icons` folder in the rapps-db repository. Alternatively, if the filename of the .txt file matches the filename of an .ico file, that icon will also be displayed.

RegName

Name in Registry

SHA1

SHA1 checksum, to verify the download. By standard SHA1 is case-insensitive.

SizeBytes

The actual size of the download in bytes. Used to display size value in the application info as well as while downloading. On Windows systems usually both nominal size and size on disk are reported, in this case use the former.

URLSite

Main web site where the program can be found. HTTPS is not mandatory but recommended.

Version

This is the version of the program. In the code it is treated as a zero terminated string, so the decimal separator shouldn't matter, RAPPS should only check if the string of the latest available version is different from the installed one.

Deprecated fields

LicenseInfo

For a while the wiki erroneously reported LicenseInfo instead of LicenseType. If it is found in a file, please simply replace it with LicenseType.[2]

Size

The Size parameter was used before the introduction of SizeBytes. It has now been removed[3].

Experimental Features

RAPPS has some experimental features that are not included yet in the current stable (0.4.13), and are only available in development (0.4.15-dev).

These work well enough to be tested and used but might still be subject to changes before being merged in stable.

Architecture-based Sections

As ReactOS has several ports (at different stages of completions), it is already possible to define different sections for different architectures. Some files in rapps-db already include different entries, but at the moment (0.4.13 release) the x86 port is the only one working.

If not differently specified, all entries are assumed to be x86.

These are the possible values for the architecture[4]:

  • [Section.x86] - i586. Can be omitted, by default all entries are supposed to be for x86.
  • [Section.amd64] - x86_64/x64
  • [Section.arm] - ARM
  • [Section.arm64] - ARM64
  • [Section.ia64] - Itanium
  • [Section.ppc] - PowerPC

Command Line Support

Apart from the graphical interface, RAPPS features command-line options that can be used to install apps. They will install exactly as if selected in the app itself.

Current available options are listed below:

  • /? - display the usage of RAPPS commandline
  • /INSTALL - accepts multiple apps as values and installs them if they are available.

Example: rapps /INSTALL 7zip akelpad

  • /SETUP - accepts a full path to the .inf file, where in [RAPPS] block you can specify which apps to install using one Install= key per single app.

Example:

[Version]
Signature = $Windows NT$
ClassGUID = {00000000-0000-0000-0000-000000000000}

[RAPPS]
Install=7zip
Install=akelpad

[Version] section is a necessary header for .INF files. [RAPPS] is a section where you specify the needed apps. Apps should be added in .INF one-by-one, as can be seen in the example.

Names used are same as the filename in database textfiles.

  • /FIND - accepts multiple strings and find all corresponding apps contains the strings in the name or description.

Example: rapps /FIND Firefox "Python 3"

  • /INFO - accepts multiple package-name and display apps information correspond with the package-name.

Example: rapps /INFO rosbe codeblocks

New Sections Fields

Languages

This field is used to inform the user whether the app is available in their language.

You should place all the language codes app supports separated by | there.

Example:

Languages=0C09|0813|0422

LicenseType

This is a field in the DB which, when present, changes the way License field in the info is shown.

Application license types correspond to a number:

  • 1 – "Open Source"
  • 2 – "Freeware"
  • 3 – "Demo/Trial"

ScreenshotN

Screenshot URL link. (N = 1, 2, 3 ...)

Currently, only first Screenshot is used. Ensure the URL is a direct link to the image, not a page containing the image (e.g. Imgur links). It is also preferred to include the screenshot taken on ReactOS, not on Windows.

This screenshot can be specified with the field 'Screenshot1'.

; Example of a current application in RAPPS with a screenshot
[Section]
Name = Code::Blocks (without compiler)
Version = 17.12
License = GPLv3
Description = An open source, cross-platform, powerful IDE. It does not contain a compiler.
Category = 7
URLSite = http://www.codeblocks.org/
URLDownload = https://download.sourceforge.net/project/codeblocks/Binaries/17.12/Windows/codeblocks-17.12-setup.exe
SHA1 = 05ad095b5e04de243df736c060aea25a554dad94
SizeBytes = 37372176
Screenshot1=https://i.imgur.com/FykFrzz.png

See Also

References