Skip to content

Running & Previewing Your App

The Apleno Designer extension integrates with VSCode's debug system to let you run and preview your application directly from the editor.

Prerequisites

Before you can run a preview:

  1. A .ppro file must exist in the workspace root.
  2. The entry sequence specified in sequenceStart (default: main.pseq) must exist.
  3. At least one language runtime must be configured (R, Python, or Conda).
  4. The Apleno Runtime must be installed on your machine (the extension manages this automatically).

Starting a Preview with F5 (Debug)

Press F5 in VSCode. If your workspace has the pgm debug configuration in .vscode/launch.json, the app will start directly. If the launch.json does not exist yet, it is created automatically.

What Happens

  1. The extension verifies the Apleno Runtime is installed.
  2. If not installed, you are prompted to download it.
  3. If an update is available, you are offered the option to install it.
  4. The runtime launches with your project configuration.
  5. The app opens automatically.

The status bar at the bottom of VSCode shows the current state (e.g. "Starting Apleno instance...").

Runtime Management

Automatic Download

If the Apleno Runtime is not yet installed, the extension will show a notification:

"To execute an Apleno app, you need the Apleno Runtime installed on your computer. Do you want to install it now?"

Click Download to begin the installation. The extension handles the download and setup automatically.

Automatic Updates

If you already have the runtime and a newer version is available, you will see:

"An Apleno Runtime update is available (installed: X.Y.Z, available: A.B.C). Do you want to download and install the update?"

You can skip the update and continue with your current version.

Configuring Language Runtimes

The extension supports three runtime environments:

R

Apleno: Choose R path for preview

Select the R.exe (Windows) or R binary (macOS/Linux) from your R installation. Typical paths:

  • Windows: C:\Program Files\R\R-4.3.0\bin\R.exe
  • macOS: /usr/local/bin/R
  • Linux: /usr/bin/R

Python

Apleno: Choose Python path for preview

Select the python.exe or python binary. For virtual environments, point to the environment's python executable.

Conda

Apleno: Choose Conda path for preview

Select the Conda executable to use a Conda-managed environment.

All paths are saved to .vscode/apleno.json:

{
  "r": { "path": "/usr/local/bin/R" },
  "python": { "path": "/usr/bin/python3" }
}

Stopping the Preview

Close the app or stop the debug session in VSCode:

  • Click the red Stop button in the debug toolbar.
  • Or press Shift+F5.

Viewing Logs

If something goes wrong or you want to inspect the runtime output, open the extension logs:

Apleno: Show logs

This opens the Apleno output channel in the VSCode panel, showing:

  • Startup and shutdown events
  • Runtime errors and warnings
  • Script execution output

R Console Access

If Console Access is set to enabled in the project settings (.ppro), the app will expose an interactive R console that users can access inside the running application. This is useful during development for inspecting the R session state.

Set it to disabled before distributing your app to end users.

Working Directory

The Default Working Directory setting in the .ppro file controls the working directory for R/Python scripts at runtime:

Value Meaning
app The scripts' working directory is the app's folder (where project.ppro lives). This is the recommended default for most projects.
output The scripts' working directory is the generated output folder. Useful for apps that produce output files and need to write relative to the output location.

Output Folder

When your app runs, it can generate an output folder. The name is controlled by the outputFolderName property in .ppro. It supports two template variables:

Variable Replaced by
{{name}} The app name from the .ppro file.
{{datetime}} The current date and time at launch (formatted for use in folder names).

Example: {{name}}_{{datetime}} → MyApp_2024-03-15_14-30-00

Troubleshooting

"No project file found"

Ensure a .ppro file exists in the root of your workspace.

Runtime not found

Run Apleno: Choose R path for preview (or Python/Conda) to re-select the interpreter path.

Script errors

R/Python errors are reported in the app's interface and in the extension logs. Use consoleAccess: "enabled" in your .ppro during development to inspect the R session interactively.