Development/Environment variables

From The Document Foundation Wiki
Jump to navigation Jump to search

This page is aimed to reference and document all the environment variables that are used in LibreOffice.

How to use environment variables

The exact syntax depends on the shell and the OS.

For Linux/bash, you can use SAL_USE_VCLPLUGIN variable to use gen UI using export command:

export SAL_USE_VCLPLUGIN=gen
instdir/program/soffice

Another approach would be using it in the same command for running soffice:

SAL_USE_VCLPLUGIN=gen instdir/program/soffice

Another way would be passing the environment variable using -env, but it only works for bootstrap variables. You should note that not every variable is a bootstrap variable.

instdir/program/soffice -env:SAL_USE_VCLPLUGIN=gen

For Windows, one should use set in order to set the environment variable. For example, to get an RTL UI, one should use SAL_RTL_ENABLED in this way:

SET SAL_RTL_ENABLED=1
path-to/soffice.exe

For one-liner in Windows to use as a shortcut, one could use set in a different way. For example, to run LO without SKIA in case of a problem and to additionally avoid restore:

C:\Windows\System32\cmd.exe /c "set SAL_DISABLESKIA=1 && START /D ^"C:\Program Files\LibreOffice\program^" soffice.exe  --norestore"

Another way would be passing the environment variable using -env (only bootstrap variables).

instdir/program/soffice -env:SAL_USE_VCLPLUGIN=gen

List of environment variables

Note pin.svg

Note:
If you want to add a new environment variable to the LibreOffice source code, please note that:

1. An environment variable is not the best way to handle the system configuration. Think about other ways of handling the system configuration that may be more appropriate.

2. Please consider adding a prefix (like SAL_) to avoid conflicts with other environment variables from other applications.

VCL

General

Variable Description
SAL_USE_VCLPLUGIN Which VCL plugin to use instead of the auto-detected one. Possible values: gen: X11 UI

qt5: Qt 5 UI
qt6: Qt 6 UI
kf5: KDE KF5 UI
gtk3: GTK 3 UI
gtk4: GTK 4 UI
gtk3_kde5: GTK 3 KDE 5 UI
win: Windows UI (Windows only)
osx: macOS X UI (macOS only)

A list of these VCL plugins can be extracted by:
grep vclplug Repository.mk in core.

SAL_RTL_ENABLED Enable right to left (RTL) UI, used for Arabic, Persian, Hebrew and other RTL languages.
SAL_NO_NWF Disable native widgets
SAL_FORCEDPI Force a specific DPI (gtk3 & qt5/kf5 plugins only)
SAL_FORCE_HC force high-contrast mode
SAL_USE_SYSTEM_LOOP Calls std::abort on nested event loop calls. Currently just for Qt with many crashes. WIP.
SAL_NO_FONT_LOOKUP Disable font search and fallback and always use a hard-coded font name (for some unit tests)
SAL_DISABLE_WATCHDOG don't start the thread that watches for broken GL/Vulkan/OpenCL drivers
SAL_NO_MOUSEGRABS for debugging - stop blocking UI if a breakpoint is hit
LO_COLLECT_UIINFO Enable the uitesting logging, value is expected to be a relative file name that will be used to write the log under instdir/uitest/.
VCL_DOUBLEBUFFERING_AVOID_PAINT Don't paint the buffer, useful to see where we do direct painting
VCL_DOUBLEBUFFERING_FORCE_ENABLE Enable double buffered painting
VCL_DOUBLEBUFFERING_ENABLE Enable a safe subset of double buffered painting (currently in Writer, not in any other applications)
VCL_DEBUG_DISABLE_PDFCOMPRESSION Disable compression in the PDF writer

GTK

Variable Description
VCL_GTK3_PAINTDEBUG in debug builds, if set to 1 then holding down shift+0 forces a redraw event, shift+1 repaints everything, and shift+2 dumps cairo frames to pngs as /tmp/frame<n>.png
GDK_SCALE=2 for X11-specific HiDPI scaling (just supports integers)

Bitmap

Variable Description
VCL_NO_THREAD_SCALE disable threaded bitmap scale
VCL_NO_THREAD_IMPORT disable threaded bitmap import
EMF_PLUS_DISABLE use EMF rendering and ignore EMF+ specifics
EMF_PLUS_LIMIT EMF+ records limit

OpenGL

Variable Description
SAL_DISABLEGL disable OpenGL use
SAL_GL_NO_SWAP disable buffer swapping if set (should show nothing)
SAL_GL_SLEEP_ON_SWAP sleep for half a second on each swap-buffers.

Skia

Variable Description
SAL_DISABLESKIA=1 force disabled Skia
SAL_ENABLESKIA=1 enable Skia, unless denylisted (and if the VCL backend supports Skia)
SAL_FORCESKIA=1 force using Skia, even if denylisted
SAL_SKIA=raster|vulkan|metal select Skia's drawing method, by default Vulkan or Metal are used if available
SAL_DISABLE_SKIA_CACHE=1 disable caching of complex images
SAL_SKIA_KEEP_BITMAP_BUFFER=1 SkiaSalBitmap will keep its bitmap buffer even after storing in SkImage

OpenGL,Skia

Variable Description
SAL_WITHOUT_WIDGET_CACHE disable LRU caching of native widget textures

Qt

Variable Description
QT_SCALE_FACTOR=2 for HiDPI testing (also supports float)
SAL_VCL_QT5_NO_FONTCONFIG ignore fontconfig provided font substitutions
SAL_VCL_QT5_NO_NATIVE disable QStyle'd controls
SAL_VCL_QT5_USE_CAIRO use cairo for text rendering and fonts (default for kf5, but not qt5)

KF5

Variable Description
SAL_VCL_KF5_USE_QFONT use QFont for text rendering (default for qt5, but not kf5)

Mac

Variable Description
SAL_FORCE_HIDPI_SCALING set to 2 to fake HiDPI drawing (useful for unit tests, windows may draw only top-left 1/4 of the content scaled)

Dark mode

Variable Description
VCL_ICONS_FOR_DARK_THEME Use dark theme for LibreOffice icons
VCL_MACOS_FORCE_DARK_MODE Enables dark mode for macOS (the implementation is incomplete)
VCL_MACOS_USE_SYSTEM_APPEARANCE Use system settings (light mode or the dark mode as configured within system preferences)

Others

Variable Description
LIBO_VCL_DEMO Used internally by vcldemo to differentiate the execution with the normal VCL main application as it does not use the complex configurations for icon themes and cursor images
VCL_DRAW_WIDGETS_FROM_FILE
VCL_DUMP_BMP_PATH
VCL_EVENT_INJECTION

test

Variable Description
LO_TEST_LOCALE the locale to be used during unit tests. Defaults to en-US.

desktop

General

Variable Description
DISPLAY X11 display to use.
OOO_DISABLE_RECOVERY Disables the recovery dialog.
OOO_EXIT_POST_STARTUP Exit right after startup, for profiling purposes.
SAL_DISABLE_USERMIGRATION Disable automatic conversion of old user configurations.

LibreOfficeKit

Variable Description
LOK_DEBUG Draw a small red rectangle in the top left corner so that it's easy to see where a new tile begins.
LOK_ALLOWLIST_LANGUAGES Set the Allowlisted languages
LOK_DEBUG_TILES Draw a small red rectangle in the top left corner so that it's easy to see where a new tile begins
SAL_LOK_OPTIONS ':' delimited options - avoiding ABI change for new parameters. Parameters can be: unipoll, profile_events, sc_no_grid_bg, sc_print_twips_msgs, notebookbar

oox

ppt

Variable Description
OOX_NO_SMARTART_WARNING don't warn on SmartArts missing their DrawingML fallback

sax

fastparser

Variable Description
SAX_DISABLE_THREADS don't thread sax parsing

Language Variables

Variable Description
ALL_LANGS
LANG
LANGUAGE
LC_ALL
LC_CTYPE
LC_MESSAGES

System Variables

Variable Description
HOME Home folder for the current user
JAVA_HOME Path to JDK folder
OS
PATH List of directories to search for the executable files. This is used on Unix/Linux, Windows, macOS and many other platforms with slight difference that Windows uses ; instead of : to separate directories.
PYTHONPATH List of directories to be added to Python sys.path
SHELL
TMP
TMPDIR
WAYLAND_DISPLAY "This tells Wayland clients which Wayland compositor to connect to. If it is not set, clients will try wayland-0 as a fallback. WAYLAND_DISPLAY is normally the name of a socket in XDG_RUNTIME_DIR, but it can also be an absolute path to a socket anywhere."
Environment variables for Wayland hackers
DESKTOP_LAUNCH
DESKTOP_SESSION
DISABLE_REDLINE
GNOME_DESKTOP_SESSION_ID
KDE_FULL_SESSION
KDE_SESSION_VERSION
SESSION_MANAGER
TEMP
TEST_LIB
XDG_CACHE_HOME
XDG_CONFIG_HOME
XDG_CURRENT_DESKTOP
XMODIFIERS

Compile/build Variables

Variable Description
CLANG_FORMAT
CLANG_THRESHOLD
CLASSPATH
CXX
DYLD_LIBRARY_PATH
ENABLE_RELEASE_BUILD
INCLUDE
INSTDIR
LIBO_LD_PATH
MSVC_USE_DEBUG_RUNTIME
MSVC_USE_INDIVIDUAL_PDBS
SRCDIR
SRC_ROOT
WORKDIR
WORKDIR_FOR_BUILD

Debug Variables

Variable Description
CRASH_DUMP_ENABLE
CPPCANVAS_DEBUG_EMFPLUS_DUMP_TO
DBG_LWPIMPORT_DIR
DBG_PDFIMPORT_DIR
HELP_DEBUG
SAL_DEBUG_UPDATES
SAL_LOG
SAL_LOG_FILE
SD_DEBUG
SAL_LOG_SYSLOG
SW_DEBUG
SW_DEBUG_DOM
SW_DEBUG_HTML_PASTE_TO
SW_DEBUG_MAILMERGE_DOCS
SW_DEBUG_RTF_PASTE_FROM
SW_DEBUG_RTF_PASTE_TO
SW_DEBUG_WRITERFILTER

LibreOffice Updater

Variable Description
LIBO_UPDATER_BUILD
LIBO_UPDATER_CHANNEL
LIBO_UPDATER_TEST_ENABLE
LIBO_UPDATER_TEST_REPLACE
LIBO_UPDATER_TEST_RUNNING
LIBO_UPDATER_TEST_UPDATE
LIBO_UPDATER_TEST_UPDATE_CHECK
LIBO_UPDATER_URL

UNO/URE Variables

Variable Description
UNODISABLELIBRARY
UNO_ENV_LOG
UNO_PATH
URE_TEST_SETTHREADNAME

Other Variables

Variable Description
AVOID_BURN_IN_FOR_GALLERY_THEME
CANVAS_SPRITE_BOUNDS
CONNECTIVITY_TEST_MYSQL_DRIVER_JDBC
CPPUNIT_TEST_NAME
FUZZ_MAX_INPUT_LEN
GALLERY_ENABLE_ID_DIALOG
GALLERY_SHOW_HIDDEN_THEMES
ISC_PASSWORD
ISC_USER
LIBO_FLATPAK
LIBO_FORMULA_LOG_FILE
LIBO_ONEWAY_STABLE_ODF_EXPORT
LIBREOFFICE_FIREBIRD_LIB
LIBREOFFICE_ICU_LIB
LO_IMPORT_USE_PDFIUM
LO_LEAN_EXCEPTION
LO_TEST_LOCALE
LO_TESTNAME
MAX_CONCURRENCY
MOZILLA_CERTIFICATE_FOLDER This is deprecated
OOO_ENABLE_LOCALE_DATA_CHECKS
OOO_FORCE_DESKTOP
OOO_INSTALL_PREFIX
PDFIMPORT_RESOLUTION_DPI
RESOURCE_NAME
SAL_ACCESSIBILITY_ENABLED
SAL_ANTIALIASED_TEXT_PRIORITY
SAL_CONFIG_WINREG_RETAIN_TMP
SAL_CUPS_PPD_RETAIN_TMP
SAL_DECIMALSEP_ENABLED
SAL_DISABLE_CAIRO_DOWNSCALE
SAL_DISABLE_CPD
SAL_DISABLE_CUPS
SAL_DISABLE_DEFAULTPRINTER
SAL_DISABLE_FLOATGRAB
SAL_DISABLE_MM02_GOODIES
SAL_DISABLE_OPENCL
SAL_DISABLE_OWN_IM_STATUS
SAL_DISABLE_PRINTERLIST
SAL_DISABLE_RENDER_POLY
SAL_DISABLE_STACKING_CHECK
SAL_DISABLE_SYNCHRONOUS_PRINTER_DETECTION
SAL_DISABLE_USE_CAIRO_FOR_FATLINES
SAL_EMBEDDED_BITMAP_PRIORITY
SAL_ENABLE_FILE_LOCKING
SAL_ENABLE_TIMER_BITMAPDRAW
SAL_ENABLE_USE_CAIRO_FOR_POLYGONS
SAL_FORCEGL
SAL_FORCE_IACCESSIBLE2 Debugging / Playing with winaccessibility: If NVDA is running when soffice starts, IA2 should be automatically enabled and work as expected. In order to use 'accprobe' to debug it is necessary to override the check for whether an AT (like NVDA) is running; to do that use: SAL_FORCE_IACCESSIBLE2=1 soffice -writer
SAL_HIGHPRIORITY_REPAINT
SAL_IGNOREXERRORS
SAL_NOLOCK_PROFILE
SAL_NO_QUERYSAVE intended for use by QA to suppress the warning on changed documents; any value is accepted even SAL_NO_QUERYSAVE="false" blocks the dialog! (tdf#143578)
SAL_NO_XINITTHREADS
SAL_PPDPARSER_LOCALE
SAL_RAND_REPEATABLE
SAL_SWITCH_OFF_ANTIALIASING_FOR_HOR_VER_BORTDERLINES
SAL_SYNCHRONIZE
SAL_TRANSPARENT_FLOATS
SAL_USEINPUTMETHOD
SAL_VISUAL
SAL_WHEELLINES
SAL_XKEYBOARDGROUP
SC_FLOAT
SC_FORCE_CALCULATION
SC_MAX_GROUP_LENGTH
SC_MAX_MATRIX_ELEMENTS
SC_NO_THREADED_CALCULATION
SC_OPENCL_DEVICE_OVERRIDE
SD_SHOW_NUMBERING_PAGE
SFX_MEDIUM_REUSE_STREAM
SOFFICE_BIN
STAR_PROFILE_LOCKING_DISABLED
STOC_FORCE_NO_JRE
STOC_FORCE_SYSTEM_LAF
SVP_LISTENER_PORT
SVX_DRAW_HANDLES
SYSTEM_BOOST
TAGLOGGERTMP
TDOC
TestUserDir
TRACE_EVENT_RECORDING

Commands

In order to retrieve the list of environment variables, use the following command on the core folder (point and dollar sign because there are such vars):

git grep -h -I 'getenv\s*(\s*"[A-Z0-9_]\+' | sed 's/.*"\([A-Za-z0-9_$.]\+\)".*/\1/g' | sort -u

When we get the list of environment variables, we want also to see where they are used. Here is the command that searches for files that use an environment variable:

git grep -I -H '"\s*ENV_VAR_NAME\s*"'

See Also