Application Runner

FAQ
, , ,
1

This is for the 2601.0 JACARANDA release only!

The following explains what the mux_launch.sh application launch script is and how applications should be launched correctly on MustardOS. This applies to all applications.

What is this mux_launch.sh script for?

The mux_launch.sh script is our standard application launcher wrapper. All applications start through this script to ensure:

  • Correct CPU governor handling
  • Proper SDL environment setup
  • Correct HOME directory assignment
  • SD1 / SD2 aware storage mounting
  • Foreground process tracking
  • Clean system state before and after launch

There isn’t much to the script but it does quite a number of different things in the background before and after your application launches.

Why do we use a launcher script?

MustardOS runs on many devices with different:

  • CPUs and performance profiles
  • Screen resolutions and rotations
  • Storage layouts (SD1 only, SD1 + SD2 etc.)
  • Power and suspend requirements

The launcher exists to:

  • Remove any confusion and abstractions away from our internal system
  • Prevent hardcoded paths from potentially breaking across devices
  • Ensure that the application runs successfully

Launcher Metadata Headers

At the top of the script you may see:

# HELP: My App is the coolest application out
# ICON: my_app_icon
# GRID: My App

These headers are parsed by the frontend.

  • HELP - Fallback help text if no mux_lang.ini file exists
  • ICON - Icon name used by the active theme
  • GRID - A short display name used in grid views

Shared System Functions

. /opt/muos/script/var/func.sh

This sources shared helper functions, including:

  • The GET_VAR and SET_VAR functions
  • Governor handling
  • Specific environment helpers

This line should NEVER be removed.

Stage Overlay System

If you would like your application to use our specific built overlay system you can do so by adding the following to your script before running the executable.

SETUP_STAGE_OVERLAY

If your application uses LD_PRELOAD this will add the overlay library to the existing LD_PRELOAD library paths.

Application Setup

After sourcing the above shared system functions you have to set up the application by specifying the executable name of what you are running:

APP_BIN="my_app_binary"
SETUP_APP "$APP_BIN" ""

You can of course use $APP_BIN within your own running script to reference the executable.

The blank ("") section after the application binary allows you to set a specific control scheme of either "modern" or "retro" which will force the application to a specific button layout.

Application Mount Paths

Applications must use:

/run/muos/storage/application/my_app

This is a bind-mounted runtime path. If the application is on SD2, it runs from SD2 otherwise it runs from SD1. Applications should not need to care where they are installed.

Do NOT hardcode either of the following mount paths:

/mnt/mmc
/mnt/sdcard

These will break on:

  • Devices with SD2
  • Different storage layouts
  • Future system changes

Application Code Itself

# -----------------------------------------------------------------------------
# You do everything else within this area here for your application

This is where your application specific logic starts. So from changing directories to setting additional environment variables. Then from here launch your executable with arguments or config files etc.

Icon Glyph

You can have a custom icon for your application and place it at glyph/my_app_icon.png which is set in the ICON section of the script.

Application Language

[full]
English=Dingux Commander
Polish=Dingux Commander

[grid]
English=Dingux
Polish=Dingux

[help]
English=A simple two-column file manager that gives you full access to be dangerous!
Polish=Prosty, dwukolumnowy menedżer plików, dający ci pełen dostęp do systemu plików!

To ensure that your application displays correctly in the frontend you can create a mux_lang.ini file alongside your mux_launch.sh runner. This will make sure that our frontend displays it with our current supported languages.

Ask Questions

If you are unsure about any part of this process, ask first rather than hardcoding paths or bypassing the launcher.

Full Example

#!/bin/sh

# HELP: My App is the coolest application out
# ICON: my_app_icon
# GRID: My App

. /opt/muos/script/var/func.sh

APP_BIN="my_app_binary"
SETUP_APP "$APP_BIN" ""

SETUP_STAGE_OVERLAY # Again this is optional

# -----------------------------------------------------------------------------
# You do everything else within this area here for your application