GeneXus Next Desktop - Setup and Troubleshooting Guide for Running Native Mobile Apps

This documentation is valid for:
GeneXus Next Help

This guide describes how to run Android and Apple applications built with GeneXus Next Desktop. It includes setup instructions and troubleshooting guidelines for common issues.

Compiling and Running an Android App

Below are described the Android-specific prerequisites:

Android SDK: Ensure the Android SDK is installed and configured correctly.
JDK: Install a Java Development Kit (JDK) that is compatible with your Android SDK.

Option 1: Using the GeneXus Android Container

This option allows you to compile the app, but not run it, since the container does not include a graphical interface.

Setup: This is the default option. The properties are preconfigured with resources included in the Android container.
- Host: Default container location
- User: Default user
- Password: Default password
- Root KB Directory: Default location
- Android SDK Directory: Default location
- JDK Directory: Default location
To run the application, you can use an Android emulator installed on your local machine to test the application after compiling it.

Consideration

When running GeneXus Next Desktop through a browser, the Android container is not started by default to optimize system resource usage (memory and processor). The Android container is only needed when you plan to compile GeneXus-generated Android applications, to enable it, follow the steps below:

Stop the running containers.
Edit the docker-compose.yml file:
- Open the docker-compose.yml file in your preferred text editor.
- Locate the gxms service section.
- Find the depends_on configuration within the gxms service.
Uncomment the Android dependency:
- Remove the comment from the android line so the depends_on section looks like this:
```
depends_on:

       -sql

       -pgsql

       -android

  
```
Start the containers again.

The Android container will now be started and configured for use. Otherwise, an error like the following is displayed when the Android container is not started:

========== Android Compilation Started ==========
error: Connection refused
Failed: Android Compilation
Failed: Build All

Example of Compiling on Windows for a Linux Container

Prerequisites: Ensure the Android container is running.
Configuration: Set the following properties:
- Host: host.docker.internal:8022
- User: builduser
- Password: View SAC #61028
- Root KB Directory: /data/kbs
- Android SDK Directory: /opt/android-sdk-linux
- JDK Directory: /usr/lib/jvm/java-17-openjdk-amd64
Error Handling: If you encounter permission errors, switch to the root user:
- User: root
- Password: View SAC #61028

Option 2: Using Local Android SDK

Setup: Change the following properties to access the host machine:
- Host: IP of the host machine
- User: SSH user
- Password: SSH password
- Root KB Directory: Local path to the KB
- Android SDK Directory: Local path to the SDK
- JDK Directory: Local path to the JDK
Notes:
- Ensure the KB path points to the host directory, not the container.
- Using your local SDK in the host, you can compile and execute the application using emulator.

Example of Compiling and Running on Windows using a local SDK

SSH Connection: Verify the SSH connection using the command:
ssh username@hostname_or_ip_address
Configuration: After launching GeneXus Next Desktop and opening the Knowledge Base (KB), configure the following properties:
- Host: IP of the machine
- User: Windows user
- Password: Windows password
- Root KB Directory: Path to GeneXus Next Desktop KBs (usually under the root directory where the clone resides, in ..\GeneXusNextDesktopInstalation\data\kbs)
- Android SDK Directory: Local path
- JDK Directory: Local path

Compiling and Running an Apple App

Before running GeneXus Next Desktop, ensure the following:

Xcode: Ensure Xcode is installed on your macOS.
Provisioning Profiles: Set up the necessary provisioning profiles and certificates in Xcode.
SSH Access: Verify SSH connection to the host machine if applicable.

Compiling and Running on macOS

GeneXus Next Desktop properties:
- Host: IP address of the host machine (if using remote execution)
- User: SSH user (if applicable)
- Password: SSH password (if applicable)
- Root KB Directory: Local path to the KB
- iOS SDK Directory: Path to the iOS SDK (usually managed by Xcode)
- JDK Directory: Path to the JDK (if required)
Building the Application:
1. Open your project in GeneXus Next Desktop.
2. Select the Apple platform.
3. Click on the Build option to compile the application.
Running the Application:
- You can run the application directly on a connected Apple device or an emulator.
- Ensure that the device is recognized by Xcode.

Common Errors and Troubleshooting

Provisioning Profile Issues: Ensure the correct provisioning profiles are selected in Xcode.
Build Failures: Review the build log for errors. Common issues include missing dependencies or incorrect paths.
Device Not Recognized: Make sure the device is connected and trusted by your macOS.

Error Message: Connection refused or Connection reset by ::1 port 22
Cause: The SSH server is not running or not configured properly.
Solution:
1. Verify that the SSH server is installed and running on the host machine.
2. Use the following command in PowerShell or Bash to check the status:
  - Get-Service sshd # For PowerShell
  - systemctl status sshd # For Bash
3. If it's not running, start the SSH service:
  - Start-Service sshd # For PowerShell
  - sudo systemctl start sshd # For Bash

Container Issues

Error Message: Container not starting or Container exited with code 1
Cause: Misconfiguration or insufficient resources.
Solution:
1. Check the logs of the container for error messages: docker logs \<container_id>
2. Ensure that the required resources (CPU, memory) are allocated to the container.
3. Restart the container and verify startup success.

Build Failures

Error Message: Build failed: Could not open file hash cache or Execution failed for task ':Panel1:javaPreCompileDebug'
Cause: Permission issues or missing dependencies.
Solution:
1. Check file permissions for the project directory and ensure that the user has the necessary access: chmod -R 755 /path/to/project
2. If using a Linux container, try running the build as the root user to bypass permission issues.
3. Ensure that all dependencies are correctly installed and configured in the environment.

Gradle Issues

Error Message: ./gradlew: Permission denied or Operation not permitted
Cause: The Gradle wrapper script may lack execute permissions.
Solution:
1. Navigate to the project directory and set execute permissions: chmod +x ./gradlew
2. If on macOS, ensure that the file does not have the quarantine attribute: xattr -d com.apple.quarantine ./gradlew

Device Not Recognized

Error Message: Device not found or No devices connected
Cause: The connected device may not be recognized by the development environment.
Solution:
1. Ensure that the device is connected via USB and is trusted by the host machine.
2. Check that the device is visible in Xcode (for Apple) or Android Studio (for Android).
3. Restart the development environment and reconnect the device.

Firewall Settings

Error Message: Request timed out or Unable to connect to the host
Cause: Firewall settings may be blocking the necessary ports.
Solution:
1. Ensure that the firewall allows inbound connections on the necessary ports (22 for SSH, 8082 for Xcode).
2. Create a new firewall rule to allow traffic on these ports:
  New-NetFirewallRule -DisplayName "Allow SSH Port 22" -Direction Inbound -Protocol TCP -LocalPort 22 -Action Allow # For PowerShell

Additional Tips

Check Logs: Always review the logs for detailed error messages. Logs often reveal the cause of a failure during execution.
Environment Variables: Ensure that all necessary environment variables are set correctly, especially for paths related to SDKs and JDKs.
Documentation: Refer to the official GeneXus Next Desktop documentation for version-specific configurations, updates, or known issues.

Additional Notes

The first time you request the device list, it may take a moment to appear. This is expected behavior. Subsequent requests should load the list immediately.

Page Id