Rebranding XCSoar¶

This guide documents how to rebrand XCSoar to another name, making it easier to create and maintain forks.

Quick Start ¶

XCSoar provides src/ProductName.hpp to centralize product name configuration.

Method 1: Build-Time Override ¶

Override macros at build time:

make PRODUCT_NAME=MyProduct PRODUCT_NAME_LC=myproduct TARGET=UNIX

Method 2: Permanent Changes ¶

Modify src/ProductName.hpp directly:

#define PRODUCT_NAME "MyProduct"
#define PRODUCT_NAME_LC "myproduct"
#define ANDROID_PACKAGE "com.mycompany.myproduct"

Then build normally:

make TARGET=UNIX

Product Name Macros ¶

The src/ProductName.hpp header provides the following macros:

Core Product Name ¶

PRODUCT_NAME: The main product name (e.g., "XCSoar"). Can be overridden at build time.
PRODUCT_NAME_LC: Lowercase version for file paths and Unix conventions (e.g., "xcsoar").
PRODUCT_NAME_A: ASCII version for help text and logging (same as PRODUCT_NAME).

Android Configuration ¶

ANDROID_PACKAGE: Android package name in reverse domain notation (e.g., "org.xcsoar").

Data Directory Paths ¶

PRODUCT_DATA_DIR: Data directory name for Windows/macOS (e.g., "XCSoarData").
PRODUCT_UNIX_SYSCONF_DIR: System-wide configuration directory on Linux/Unix. Derived from: "/etc/" PRODUCT_NAME_LC → "/etc/xcsoar"
PRODUCT_UNIX_HOME_DIR: User home directory on Linux/Unix. Derived from: "." PRODUCT_NAME_LC → ".xcsoar"

Platform-Specific Paths ¶

The product name macros automatically generate appropriate paths for each platform:

Platform	Data Directory	Notes
Linux/Unix	`~/.xcsoar`	Hidden, follows Unix conventions
Windows	`%LOCALAPPDATA%\XCSoarData`	Visible folder
macOS (desktop)	`~/XCSoarData`	Visible, macOS users prefer this
iOS	`~/Documents/XCSoarData`	Visible via iTunes file sharing
System-wide	`/etc/xcsoar`	Global config on Linux/Unix

Files Using Product Name ¶

The following files automatically use the product name macros:

Source Code Files ¶

src/Version.cpp - Version strings
src/Version.hpp - Version declarations
src/LocalPath.cpp - Data directory paths
src/Gauge/LogoView.cpp - Product token display
src/XCSoar.cpp - Help text
src/MainWindow.hpp - Window title

Build System Files ¶

build/main.mk - Program name
build/android.mk - Android package
build/version.mk - Version defines

Android Files ¶

android/res/values/strings.xml - App display name
android/AndroidManifest.xml.in - Android manifest

What Needs Manual Changes ¶

For a complete rebrand, some files still require manual editing:

Version Symbol Names ¶

src/Version.cpp and src/Version.hpp use hardcoded XCSoar_* symbol names:

XCSoar_Version
XCSoar_VersionLong
XCSoar_VersionString
XCSoar_ProductToken

These can be kept as-is (they’re internal symbols) or changed manually if desired.

Android Display Name ¶

android/res/values/strings.xml contains:

<string name="app_name">XCSoar</string>
<string name="app_name_testing">XCS-test</string>

These could be changed manually or via build-time substitution.

Logo and Graphics ¶

Replace graphics files in:

Data/graphics/ - Logo and splash screen images
Data/iOS/Assets.xcassets/ - iOS app icons

Usage Examples ¶

Example 1: Quick Test Build ¶

Build XCSoar as “MyGlider” for testing:

make PRODUCT_NAME=MyGlider PRODUCT_NAME_LC=myglider TARGET=UNIX

Result:

Binary name: myglider (Linux) or MyGlider (Windows)
Data directory: %LOCALAPPDATA%\MyGliderData (Windows), ~/MyGliderData (macOS), or ~/.myglider (Linux)
System config: /etc/myglider

Example 2: Permanent Fork ¶

For a permanent fork, edit src/ProductName.hpp:

#ifndef PRODUCT_NAME
#define PRODUCT_NAME "OpenSoar"
#endif

#ifndef PRODUCT_NAME_LC
#define PRODUCT_NAME_LC "opensoar"
#endif

#ifndef ANDROID_PACKAGE
#define ANDROID_PACKAGE "de.opensoar"
#endif

Then build normally:

make TARGET=UNIX

Example 3: Android Build ¶

Build an Android APK with custom branding:

make PRODUCT_NAME=MyGlider PRODUCT_NAME_LC=myglider \
     ANDROID_PACKAGE=com.mycompany.myglider \
     TARGET=ANDROID

Comparison with Other Forks ¶

OpenSoar Rebranding Analysis ¶

The OpenSoar fork demonstrates a complete rebranding. Here’s what they changed:

Configuration File ¶

Created OpenSoar.config in the root directory:

PROGRAM_NAME=OpenSoar
PROGRAM_VERSION=7.43-3.24.1
ANDROID_VERSIONCODE=24
ANDROID_PACKAGE=de.opensoar

Key Changes ¶

Category	XCSoar	OpenSoar
Data Directory (Windows)	`XCSoarData`	`OpenSoarData`
Home Directory (Linux)	`~/.xcsoar`	`~/.opensoar`
Version Symbols	`XCSoar_Version`	`OpenSoar_Version`
Android Package	`org.xcsoar`	`de.opensoar`
App Display Name	“XCSoar”	“OpenSoar”
System Config Dir	`/etc/xcsoar`	`/etc/opensoar`

XCSoar vs OpenSoar Approach ¶

OpenSoar Approach:

❌ Hardcoded OpenSoar_* symbols in Version.cpp
❌ Direct string replacements throughout codebase
✅ Centralized config file (OpenSoar.config)
⚠️ Changed from TCHAR to char (breaks Windows Unicode)

XCSoar Approach:

✅ Single header file (ProductName.hpp)
✅ Build-time override support
✅ Smart macro composition (e.g., "/etc/" + PRODUCT_NAME_LC)
⚠️ Version symbols still use XCSoar_* (acceptable for internal use)
⚠️ Changed from TCHAR to char (breaks Windows Unicode)

Advantages ¶

XCSoar’s approach offers several advantages:

Easier to maintain - Single header file vs. scattered changes
Preserves compatibility - Keeps cross-platform features like TCHAR
Build-time flexibility - Can test different names without committing
Less invasive - Doesn’t require changing internal symbol names

Testing Checklist ¶

When rebranding XCSoar, verify:

User Interface ¶

☑ Program name appears correctly in title bar
☑ About dialog shows correct product name
☑ Help text references correct product name
☑ Version display shows correct product name

File System ¶

☑ Data directory location (check ~/.productname on Linux)
☑ Config file location (/etc/productname on Linux)
☑ Log files use correct product name

Android ¶

☑ Android package name is correct
☑ App installs with correct name
☑ App icon displays correctly
☑ App appears correctly in Android launcher

Flight Data ¶

☑ IGC files use correct product name (if applicable)
☑ Flight logs reference correct product name

Advanced Customization ¶

For forks requiring deeper customization beyond the product name:

Custom Versioning ¶

XCSoar’s version system uses:

VERSION.txt - Base version number
build/version.mk - Version processing
XCSOAR_VERSION macro - Version string
GIT_COMMIT_ID macro - Git commit hash

Custom Build System ¶

For forks using CMake (like OpenSoar), see their CMakeLists.txt for integration with build systems other than GNU Make.

Custom Features ¶

When adding fork-specific features:

Use #ifdef HAVE_FEATURE_NAME for conditional compilation
Add feature detection in build/options.mk
Keep core XCSoar code unmodified when possible
Document your changes in your fork’s documentation

Contributing Improvements ¶

If you develop improvements to XCSoar’s rebranding system:

Ensure changes maintain backward compatibility
Test on multiple platforms (Linux, Windows, Android)
Update this documentation
Submit a pull request to upstream XCSoar

See Policy for contribution guidelines.

Frequently Asked Questions ¶

Do I need to change the version symbols (`XCSoar_Version`, etc.)?¶

No. These are internal C++ symbols and don’t affect the user-visible product name. Most forks keep these as-is.

If you want to change them, you’ll need to:

Modify src/Version.cpp and src/Version.hpp
Update all references to these symbols throughout the codebase

Will upstream merges break my rebranding?¶

No. By keeping your changes in src/ProductName.hpp, you can merge upstream XCSoar changes without conflicts. The header file is designed to be fork-friendly.

Can I use the same data directory as XCSoar?¶

Yes, but not recommended. If you set:

#define PRODUCT_NAME_LC "xcsoar"

Your fork will use ~/.xcsoar, sharing the same config with XCSoar. This can be useful for testing but may confuse users.

How do I change the splash screen and logo?¶

Replace the image files in:

Data/graphics/logo.svg - Main logo
Data/graphics/logo_*.svg - Platform-specific logos
Data/graphics/splash_*.bmp - Splash screens

The build system will automatically process these during compilation.

Can I distribute my rebranded fork?¶

Yes, under the terms of XCSoar’s GPL-2.0-or-later license. You must:

Keep the GPL license
Provide source code to your users
Credit the XCSoar Project
Document your changes

See COPYING for full license terms.