This wrapper sets up development environment before launching the editor inside flatpak sandbox.
Current functions:
/usr/lib/sdk
)
FLATPAK_ENABLE_SDK_EXT
must be set to a comma-separated list or *
/app/tools
)Usage of this module consists of:
Some aspects of this module's behaviour may be changed using environment variables, see the full listing in the "Environment Variables" section below.
To use this repository as a git submodule, you may clone it inside of your flatpak's build directory with the command:
git submodule add https://github.com/flathub/ide-flatpak-wrapper.git
Then, you will bring it into your build file using flatpak-builder's "dir" source. Example:
- name: ide-flatpak-wrapper
buildsystem: meson
config-opts:
# your config opts (more on this later)
sources:
- type: dir
path: ide-flatpak-wrapper
If you prefer, you may use the git source instead. Exemple:
- name: ide-flatpak-wrapper
buildsystem: meson
config-opts:
# your config opts (more on this later)
sources:
- type: git
url: https://github.com/flathub/ide-flatpak-wrapper.git
branch: master
For this module to work properly, we must specify a minimum of 2 options - the path to your editor's binary and a name to install the wrapper under:
- name: ide-flatpak-wrapper
buildsystem: meson
config-opts:
# Path to the editor executable
- -Deditor_binary=/app/main/bin/code-oss
# Install wrapper under this name (must be different from the above)
- -Dprogram_name=code-oss-wrapper
sources:
# your source choice
Additionally, you may specify the following options:
-Deditor_args
Command line args to append to the editor executable.-Deditor_title
Human readable title of the editor. This will be interpolated into the "first run template"
file (more on this file later).-Dfirst_run_template
Name of the file that will be opened on your editor's first run.-Dsdk_update_template
Name of the file that will be opened when your flatpak updates its SDK. This can be
used to inform the user that the SDK extensions they were using before must be updated as well.-Dflagfile_prefix
An arbitrary string prepended to -first-run
and -sdk-update-
files names that indicate
that we already did show the corresponding readme.-Ddefault_loglevel
The default loglevel. May be overwritten by user with FLATPAK_IDE_LOGLEVEL environment variable.Now that you have your wrapper configured, you must ensure it is executed instead of your actual editor's
binary. Typically your flatpak will have two entry points: the command
key of your build file which is used
when the flatpak is executed using the flatpak run
command and the desktop file which is used when the user
clicks on your editor's icon from their desktop environment. If the desktop file comes from upstream you will
need to patch the Exec
line to call the wrapper.
To inform your user of the particulars of flatpaks, you can include a first run template and an SDK update template
which will be run once after each of those events. You must include those files in the sources
section of the
module:
- name: ide-flatpak-wrapper
buildsystem: meson
config-opts:
# your options
sources:
# your source choice
- type: file
path: ide-first-run.txt
- type: file
path: sdk-update.txt
Those template files have string interpolation for the EDITOR_TITLE
and FLATPAK_ID
using the @
symbol.
For example, using an editor title of "VS Code" and a flatpak ID of "com.visualstudio.code" the template file
would go from this:
------------------------------------------------------------------------------------
| Warning: You are running an unofficial Flatpak version of @EDITOR_TITLE@ !!! |
------------------------------------------------------------------------------------
Please open issues under: https://github.com/flathub/@FLATPAK_ID@/issues
To this:
------------------------------------------------------------------------------------
| Warning: You are running an unofficial Flatpak version of VS Code !!! |
------------------------------------------------------------------------------------
Please open issues under: https://github.com/flathub/com.visualstudio.code/issues
You may use the following environment variables to change the behaviour of the ide-flatpak-wrapper:
FLATPAK_IDE_LOGLEVEL
(= 1
)
Controls verbosity of the module, 0
supresses all module-originated outputs to stdout.
0
| 1
)FLATPAK_PREFER_USER_PACKAGES
(= 0
)
FLATPAK_ISOLATE_PACKAGES
(= 1
)
FLATPAK_ISOLATE_NPM
(= FLATPAK_ISOLATE_PACKAGES
)
FLATPAK_PREFER_USER_NPM
(= FLATPAK_PREFER_USER_PACKAGES
)
FLATPAK_ISOLATE_CARGO
(= FLATPAK_ISOLATE_PACKAGES
)
FLATPAK_PREFER_USER_CARGO
(= FLATPAK_PREFER_USER_PACKAGES
)
FLATPAK_ISOLATE_PIP
(= FLATPAK_ISOLATE_PACKAGES
)
FLATPAK_PREFER_USER_PIP
(= FLATPAK_PREFER_USER_PACKAGES
)