Running AFRYCA is very easy, it is not necessary to perform in most cases any additional tasks to the download and decompression of the application. For this reason, its installation guide is brief and for the most part is made up of suggestions and warning notes that will avoid setbacks when using the application.

The guide is divided into two parts, requirements and deployment, which are recommended to read in full before running AFRYCA.

Requirements

The only requirement to run AFRYCA is to have the appropriate Java runtime installed on the system. In addition, if you want to use R from the AFRYCA scripting environment, you must install this statistical environment and its configuration for integration with the application.

Installing Java

Java is a general purpose programming language designed specifically for the development of cross-platform applications. Applications developed in Java run on a virtual machine called Java Virtual Machine (JVM) for which there are currently different implementations such as OpenJDK or developed by Oracle.

To run an application developed in Java it is necessary to have an operating JVM in the system. The following is indicated that must be taken into account to install a version of the JVM that allows to execute AFRYCA.

• Java version: On February 2017, Java versions range from 1.0 to 1.8. The successive versions of Java are backward compatible with previous versions, so installing the latest version of the JVM should not be any problem to run any program developed in Java. However, this does not happen in all cases and sometimes it is necessary to install obsolete versions of Java to support specific software. This does not happen in the case of AFRYCA, so unless there is a limitation in the system, we recommend installing the latest available version of the JVM. If this is not possible, it will be necessary to have:
  • Java 1.7 or higher to run the versions previous to AFRYCA 3.
  • Java 1.8 or higher from AFRYCA 3.
• JVM 'flavor': Usually, Java is distributed in two 'flavors', Java Runtime Environment (JRE),which is intended for those users who want to run applications developed in Java and Java Develpment Kit (JDK), which is intended for those users who also want to develop Java applications. As is the case, to run AFRYCA you need only install JRE.

• Arquitectura: The JVM is available for both 32-bit and 64-bit architectures. Even if in hardware of 32 bits it is only possible to execute a JVM of 32 bits, in hardware of 64 bits is possible to execute JVMs of 32 and 64 bits. Therefore, unless a hardware with 32-bit hardware is available, the version of the programs to run in the JVM will not depend on the system architecture but on the architecture of the JVM. AFRYCA is available for both types of architectures so you only have to consider the architecture of the JVM installed in the system and not whether it is compatible with AFRYCA or not. Although the architecture version is not a problem for AFRYCA execution, here are a few tips to detect and solve problems caused by the use of an inappropriate version of AFRYCA:
  • If the system has an already installed JVM and the version is unknown it is possible to know it by running the command 'java -version' in the console. The output of this command will give some basic information about the version of the JVM in use and, if it is a 64-bit version, this will be indicated in this information. Otherwise the version of the JVM will be 32 bits.
  • At the time of writing this guide, the Oracle JVM main download page only includes a link to download the 32-bit JVM. To download a 64-bit version you must access the manual download section of the web.
  • It is not possible to run an AFRYCA version that is not compatible with the system JVM. If you try to run the application it will fail as a result of multiple errors difficult to determine a priori. What you can guarantee is that these errors will occur as soon as you run the application. If running the application for the first time shows an error window, in most cases this is because the architecture of the application and the JVM are not the same.

Java is a software widely used by all types of users, so its installation is a simple and easy process to follow with the instructions that are in the page of downloads of the JVM. Even so, the following guide can be helpful in resolving possible problems that may appear in your installation.

R installation

R is a statistical analysis environment and a programming language. At present, language has a wide acceptance among the scientific community, which has led to the appearance of a large number of libraries of all kinds.

In AFRYCA it is possible to use R as a more scripting environment and thus access its wide range of libraries. However, the installation of R is a process that will not be trivial in many cases, and its proper configuration for proper integration with AFRYCA requires several actions, so if you do not want to use R you can skip this section.

Once AFRYCA is started, if the application configuration does not make it possible to use R, the following dialog will be displayed, in which the necessary steps for its correct configuration are summarized. The dialog title shows the exact error that has prevented your upload.

Failed to load R

Checking the option 'Do not show faults again by loading R' this dialog will not show again in successive executions. You can reconfigure the appearance of this dialog by opening the preferences window 'ASE> Environments> R> Preferences of R' and deactivating the 'Do not show faults loading R' option again. Regardless of the previous dialog, it is possible to know the status of R at any selected time 'ASE> Environments> R> Show R' status. If the R configuration is not correct, the help dialog for your configuration will be displayed. If the R configuration is correct, the configuration parameters will be displayed.

State of R

If you want to use R in AFRYCA, but this statistical environment has never been used before, we refer you to the R help page where updated and detailed information about your installation and configuration process is available. Once installed R, simply follow the information offered by AFRYCA to perform its configuration.

When performing the R configuration, special care should be taken to the following points:

• The JRI must be configured for the architecture of the installed rJava package. This architecture is not related either to the system architecture, to the JVM used, to the AFRYCA version, or to the R version. Note that a 64-bit R installation can use libraries of both 32 bits as 64 bits and that the JRI represents an interface that allows us to use R from Java, so that all kinds of combinations can be given.
• Use the spacer bars as is indicated.
• Follow the instructions regarding the use of quotation marks and apostrophes.

Deployment

AFRYCA is an Eclipse RCP application, a platform for the development of applications under a component architecture. In a rough way, the application can be seen as a set of plug-ins encompassed in different features. Among all the plug-ins of the application there is one of them that includes the application model, which establishes the basic structure of the application and on which the others add their functionality.
Downloading AFRYCA provides a container file with a number of elements, among which we highlight the following:

• features/: Set of features that make up the application.
• plugins/: Set of plug-ins provided by the features of the application.
• configuration/: Configuración de la aplicación (contenedor de componentes, enlace al modelo de aplicación, etc).
• workspace/: Configuration of the application (container components, link to the application model, etc).
• afryca.ini: Configuration of application initialization (log level, coding, paths, etc).
• afryca: Launcher application.

To run AFRYCA simply unzip the container and run the launcher of the application. However, before doing so, consider that this action involves the creation of the workspace folder, which will cause the application to be linked to the current directory. After this folder is created, any changes to the directory will cause the application to fail. While this folder can be deleted to force the application to create it again, keep in mind that the workspace folder is used by both the Eclipse RCP base components and AFRYCA, which establishes its workspace here, so its Elimination could lead to loss of problems, configuration logs or scripts.

However, it should be noted that AFRYCA only uses the same workspace folder created as its initial workspace to conform to the conventions in the development of Eclipse RCP applications. From the same application you can modify the folder that AFRYCA will use as workspace to be different from the one used as the workspace of Eclipse RCP and thus avoid the loss of files when deleting the workspace directory.

As stated, after the creation of the workspace folder the application is linked to the directory from which the launcher is executed. Therefore, if you want to create a direct link to the application that is not in the same directory, keep in mind that this link must be relative to the directory of the application.

Creating a launcher may be a good idea to avoid accessing the AFRYCA installation folder every time you want to run the application as well as to provide specific configuration parameters. Some interesting parameters that can be used are indicated below:

• -nl <en|es>: Force the use of a language.
• -consoleLog: Show application log.
• -clearPersistedState: Clear configuration of past executions.
• -vmargs: Arguments specific to the JVM.

You can obtain a complete list of supported parameters in the following link.