Skip to content

BUILD.md

Latest commit

 

History

History
963 lines (733 loc) · 24.3 KB

BUILD.md

File metadata and controls

963 lines (733 loc) · 24.3 KB
Raw

px4xplane Build Guide

A comprehensive guide for building the px4xplane X-Plane plugin on Windows, macOS, and Linux systems.

Repository: alireza787b/px4xplane

Table of Contents

Quick Start

CMake (Recommended - All Platforms)

# 1. Clone and prepare
git clone --recursive https://github.com/alireza787b/px4xplane.git
cd px4xplane

# 2. Build
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build .

# 3. Your plugin is ready at:
# Windows: build/win/release/px4xplane/64/win.xpl
# macOS: build/mac/release/px4xplane/64/mac.xpl
# Linux: build/lin/release/px4xplane/64/lin.xpl

Windows (Visual Studio)

# 1. Clone and prepare
git clone https://github.com/alireza787b/px4xplane.git
cd px4xplane
git submodule update --init --recursive

# 2. Open in Visual Studio
# Double-click px4-xplane.sln or open via Visual Studio

# 3. Build
# Press Ctrl+Shift+B or Build > Build Solution

# 4. Your plugin is ready at:
# build/windows/release/plugins/px4xplane/64/win.xpl

macOS/Linux (Native Makefiles)

# 1. Clone and prepare
git clone https://github.com/alireza787b/px4xplane.git
cd px4xplane
git submodule update --init --recursive

# 2. Build
# Linux:
make -f Makefile.linux

# macOS:
make -f Makefile.macos

# 3. Your plugin is ready at:
# Linux: build/linux/release/px4xplane/64/lin.xpl
# macOS: build/macos/release/px4xplane/64/mac.xpl

Prerequisites

System Requirements

Windows:

  • Windows 10 or later (64-bit)
  • Visual Studio 2019 or 2022 (Community/Professional/Enterprise)
  • X-Plane 11 or 12

macOS:

  • macOS 10.14 or later
  • Xcode Command Line Tools
  • X-Plane 11 or 12

Linux:

  • Ubuntu 18.04+ / Debian 10+ / CentOS 7+ or equivalent
  • GCC 7+ or Clang 6+
  • X-Plane 11 or 12

Required Dependencies

Install Build Tools

Windows:

  1. Install Visual Studio 2019 or 2022:
    • Download from Visual Studio Downloads
    • Choose "Desktop development with C++" workload during installation
    • Ensure "MSVC v143 compiler toolset" and "Windows 10/11 SDK" are selected

macOS:

# Install Xcode Command Line Tools
xcode-select --install

Ubuntu/Debian:

sudo apt update
sudo apt install build-essential g++ make
sudo apt install libgl1-mesa-dev libglu1-mesa-dev

CentOS/RHEL/Fedora:

# CentOS/RHEL
sudo yum groupinstall "Development Tools"
sudo yum install mesa-libGL-devel mesa-libGLU-devel

# Fedora
sudo dnf groupinstall "Development Tools"
sudo dnf install mesa-libGL-devel mesa-libGLU-devel

Project Dependencies

The following are automatically handled by the build system:

  • X-Plane SDK - Already included in lib/SDK/
  • MAVLink v2 - Git submodule in lib/mavlink/
  • SimpleINI - Git submodule in lib/simpleini/
  • Eigen - Included in lib/Eigen/
  • XYZgeomag - Git submodule in lib/XYZgeomag/

Project Structure

px4xplane/
├── src/                    # Source code
│   ├── ConfigManager.cpp
│   ├── configReader.cpp
│   ├── ConnectionManager.cpp
│   ├── DataRefManager.cpp
│   ├── MAVLinkManager.cpp
│   ├── px4xplane.cpp
│   └── TimeManager.cpp
├── include/                # Header files
├── lib/                    # Dependencies
│   ├── SDK/               # X-Plane SDK
│   ├── mavlink/           # MAVLink library (submodule)
│   ├── simpleini/         # SimpleINI library (submodule)
│   ├── Eigen/             # Eigen math library
│   └── XYZgeomag/         # Geomag library (submodule)
├── config/                # Configuration files
├── build/                 # Build output (created during build)
│   ├── macos/            # macOS builds
│   └── linux/            # Linux builds
└── Makefile              # Build system

Build Methods

CMake (Recommended - Cross-Platform)

CMake is the modern, unified build system that works seamlessly on Windows, Linux, and macOS. This is the recommended method for all platforms.

Why CMake?

  • ✅ Single build system for all platforms
  • ✅ Industry standard for C++ cross-platform projects
  • ✅ Auto-detects platform and configures correctly
  • ✅ IDE integration: Works with VS Code, CLion, Xcode, Visual Studio
  • ✅ Easy for contributors: Just cmake . && make

Step 1: Clone Repository

git clone --recursive https://github.com/alireza787b/px4xplane.git
cd px4xplane

If you already cloned without --recursive:

git submodule update --init --recursive

Step 2: Configure Build

Linux/macOS:

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release

Windows (Visual Studio):

mkdir build
cd build
cmake .. -G "Visual Studio 17 2022" -A x64

Windows (MinGW):

mkdir build
cd build
cmake .. -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release

Step 3: Build

All platforms:

cmake --build . --config Release

Or use native build tools:

  • Linux/macOS: make
  • Windows (VS): Open px4xplane.sln in build directory
  • Windows (MinGW): mingw32-make

Step 4: Locate Output

build/
├── win/release/px4xplane/    # Windows
├── lin/release/px4xplane/    # Linux
└── mac/release/px4xplane/    # macOS
    ├── 64/
    │   └── {platform}.xpl    # Plugin binary (win.xpl/lin.xpl/mac.xpl)
    ├── config.ini            # Configuration file
    └── README.md             # Documentation

CMake Build Options

Custom compiler:

cmake .. -DCMAKE_CXX_COMPILER=clang++

Verbose build:

cmake --build . --verbose

Parallel build (faster):

cmake --build . -j$(nproc)  # Linux/macOS
cmake --build . -j%NUMBER_OF_PROCESSORS%  # Windows

Debug build:

cmake .. -DCMAKE_BUILD_TYPE=Debug
cmake --build .

Windows Build (Visual Studio)

Initialize Project

First time setup:

  1. Clone the repository:

    git clone https://github.com/alireza787b/px4xplane.git
cd px4xplane

  2. Initialize submodules:

    git submodule update --init --recursive

  3. Verify project structure:

    dir lib
# Should show: Eigen, mavlink, SDK, simpleini, XYZgeomag

Building with Visual Studio

Method 1: Visual Studio IDE (Recommended)

  1. Open the solution:

    • Double-click px4-xplane.sln
    • Or: File → Open → Project/Solution → Select px4-xplane.sln

  2. Select configuration:

    • Release (recommended for final use): Optimized, smaller file
    • Debug (for development): Debug symbols, easier debugging

  3. Build the project:

    • Press Ctrl+Shift+B
    • Or: Build → Build Solution
    • Or: Right-click project → Build

  4. Monitor build progress:

    Build started...
1>------ Build started: Project: px4xplane, Configuration: Release x64 ------
1>Compiling sources...
1>Linking...
1>Post-build: Copying configuration files
1>Build completed: build/windows/release/win.xpl
1>Plugin ready for X-Plane installation
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

Method 2: Command Line (MSBuild)

# Open "Developer Command Prompt for VS 2022"

# Build Release version
msbuild px4-xplane.sln /p:Configuration=Release /p:Platform=x64

# Build Debug version
msbuild px4-xplane.sln /p:Configuration=Debug /p:Platform=x64

# Clean and rebuild
msbuild px4-xplane.sln /p:Configuration=Release /p:Platform=x64 /t:Clean,Build

Build Output

After successful build:

Release build:

build/windows/release/
├── win.xpl              # X-Plane plugin (main file)
├── config.ini           # Configuration file (copied automatically)
└── win.pdb              # Debug symbols (for troubleshooting)

Debug build:

build/windows/debug/
├── win.xpl              # X-Plane plugin with debug info
├── config.ini           # Configuration file
└── win.pdb              # Debug symbols

Project Configuration Details

The Visual Studio project is configured with:

Include Directories:

  • include/ - Project headers
  • lib/SDK/CHeaders/XPLM/ - X-Plane SDK XPLM
  • lib/SDK/CHeaders/Widgets/ - X-Plane SDK Widgets
  • lib/mavlink/c_library_v2/ - MAVLink library
  • lib/simpleini/ - SimpleINI library
  • lib/Eigen/ - Eigen math library
  • lib/XYZgeomag/src/ - Geomagnetic library
  • config/ - Configuration headers

Preprocessor Definitions:

  • IBM=1 - Windows platform identifier
  • XPLM200=1 through XPLM400=1 - X-Plane SDK versions
  • _CRT_SECURE_NO_WARNINGS - Suppress MSVC warnings

Libraries:

  • XPLM_64.lib - X-Plane SDK main library
  • XPWidgets_64.lib - X-Plane SDK widgets
  • Opengl32.lib - OpenGL graphics
  • ws2_32.lib - Windows sockets

Alternative: Windows Makefile (MSYS2/MinGW)

For developers who prefer command-line builds on Windows:

Setup MSYS2 Environment

  1. Install MSYS2:

  2. Install build tools:

    # Open "MSYS2 MinGW 64-bit" terminal
pacman -S mingw-w64-x86_64-gcc
pacman -S mingw-w64-x86_64-make
pacman -S git

  3. Build with Windows Makefile:

    # Navigate to project directory
cd /c/path/to/px4xplane

# Use the Windows-specific Makefile
make -f Makefile.windows

# Or copy it as the main Makefile
cp Makefile.windows Makefile
make

Note: The Windows Makefile is provided separately for MSYS2/MinGW users. Most Windows developers should use Visual Studio as described above.

macOS/Linux Build (Makefile)

Initialize Submodules

First time setup only:

git submodule update --init --recursive

This downloads the required MAVLink, SimpleINI, and XYZgeomag libraries.

Basic Build Commands

Build release version (recommended):

make
# or explicitly:
make release

Build debug version:

make debug

Clean build files:

make clean

Complete clean:

make distclean

Build Output

After successful build, you'll find:

macOS:

build/macos/release/mac.xpl      # Release plugin
build/macos/debug/mac.xpl        # Debug plugin

Linux:

build/linux/release/linux.xpl   # Release plugin
build/linux/debug/linux.xpl     # Debug plugin

Configuration Options

Build Configurations

Configuration Description Use Case
release Optimized (-O3), no debug symbols Production use, best performance
debug Debug symbols (-g), no optimization Development, debugging

Environment Variables

Variable Description Example
CONFIG Build configuration CONFIG=debug make
CXX C++ compiler CXX=clang++ make
XPLANE_DIR X-Plane installation See installation section

Advanced Build Options

Use specific compiler:

CXX=clang++ make

Force debug build:

CONFIG=debug make

Parallel build (faster on multi-core systems):

make -j$(nproc)    # Linux
make -j$(sysctl -n hw.ncpu)  # macOS

Cross-Platform Building from Windows

Q: Can I build all versions (Windows, Linux, macOS) from my Windows machine?

Answer Summary:

Target Platform From Windows Method Difficulty
Windows ✅ Yes Native (Visual Studio/CMake) Easy
Linux ✅ Yes WSL2 (essentially Linux) Easy
macOS ❌ No Impossible without Mac Impossible

Building Windows Version (Native)

✅ Works perfectly - Use Visual Studio or CMake as documented above.

Building Linux Version from Windows

✅ Yes - Use WSL2 (Windows Subsystem for Linux)

WSL2 is essentially running Linux on your Windows machine. This is the recommended approach.

Setup (one-time):

# In PowerShell (Administrator):
wsl --install -d Ubuntu-22.04

Build Linux version:

# In WSL2 Ubuntu terminal:
cd /mnt/c/Users/YourName/source/repos/px4xplane

# Install prerequisites (first time only):
sudo apt update
sudo apt install build-essential

# Build:
make -f Makefile.linux

# Output will be: build/linux/release/px4xplane/64/lin.xpl

Accessing Windows files from WSL2:

  • Your C: drive is at /mnt/c/
  • Example: C:\Users\John\source\repos\px4xplane → /mnt/c/Users/John/source/repos/px4xplane

Building macOS Version from Windows

❌ No - Not Possible

Why it's impossible:

  1. Apple-only frameworks: macOS requires XPLM.framework and XPWidgets.framework that only exist on macOS
  2. Apple toolchain: Clang with Apple modifications, macOS SDK, code signing tools
  3. Legal restrictions: Apple does not permit macOS to run in VMs on non-Apple hardware
  4. No cross-compiler: There is no Windows → macOS cross-compiler that works with frameworks

Your options for macOS builds:

  1. Use actual Mac hardware (MacBook, iMac, Mac Mini, etc.)
  2. Rent cloud Mac: MacStadium, MacinCloud
  3. GitHub Actions: Free macOS runners for open-source projects
  4. Ask a contributor with Mac to build and send you the binary

Recommended: Use GitHub Actions (CI/CD)

Best practice for multi-platform builds:

Add .github/workflows/build.yml to automatically build all platforms:

  • ✅ Windows build on Windows runner
  • ✅ Linux build on Ubuntu runner
  • ✅ macOS build on macOS runner

This is how professional open-source projects do it - automated builds on every commit!

Installation

Step 1: After Successful Build

After building successfully, you'll find a complete px4xplane folder ready to use:

Build output locations:

  • Windows (CMake): build/win/release/px4xplane/
  • Windows (Visual Studio): build/windows/release/plugins/px4xplane/
  • Linux: build/lin/release/px4xplane/
  • macOS: build/mac/release/px4xplane/

This folder contains everything you need:

px4xplane/
├── 64/
│   └── {platform}.xpl    # win.xpl, lin.xpl, or mac.xpl
├── config.ini            # ✓ Already included!
├── px4_airframes/        # PX4 airframe parameter mirrors (CMake packages)
└── README.md             # Documentation

Step 2: Copy to X-Plane

Simply copy the entire px4xplane folder into your X-Plane's Resources/plugins/ directory.

Typical X-Plane plugin paths:

  • Windows: C:\X-Plane 12\Resources\plugins\
  • Linux: ~/X-Plane 12/Resources/plugins/ or /path/to/X-Plane 12/Resources/plugins/
  • macOS: /Applications/X-Plane 12/Resources/plugins/

You can do this by:

  1. Opening Windows Explorer / Finder / File Manager
  2. Navigate to your build output folder
  3. Copy the px4xplane folder
  4. Paste it into X-Plane 12/Resources/plugins/

Final result should be:

X-Plane 12/Resources/plugins/px4xplane/
├── 64/
│   └── win.xpl (or lin.xpl or mac.xpl)
├── config.ini
└── README.md

Step 3: Verify Installation

  1. Launch X-Plane
  2. Check Plugin Admin:
    • Go to: Plugins → Plugin Admin
    • Look for px4xplane in the list (should show as enabled)
  3. Check Menu Bar:
    • You should see a "PX4 X-Plane" menu in the menu bar

If the plugin doesn't appear, check X-Plane's Log.txt:

  • Windows: Documents/X-Plane 12/Log.txt
  • macOS: ~/Desktop/X-Plane 12/Log.txt
  • Linux: ~/X-Plane 12/Log.txt

Look for lines containing "px4xplane" for error messages.

Optional: Command-Line Installation

For advanced users who prefer command line:

Windows (PowerShell/CMD):

# From project root directory
xcopy /E /I "build\win\release\px4xplane" "C:\X-Plane 12\Resources\plugins\px4xplane"

Linux:

# From project root directory
cp -r build/lin/release/px4xplane "/path/to/X-Plane 12/Resources/plugins/"

macOS:

# From project root directory
cp -r build/mac/release/px4xplane "/Applications/X-Plane 12/Resources/plugins/"

Optional: Automatic Installation (Makefiles Only)

If you built with Makefile.linux or Makefile.macos, you can use the built-in install target:

Linux:

make -f Makefile.linux install XPLANE_DIR="/path/to/X-Plane 12"

macOS:

make -f Makefile.macos install XPLANE_DIR="/Applications/X-Plane 12"

Note: This is optional - manual copy (above) works just fine!

Troubleshooting

Common Issues

Build Errors

Windows: "XPLM_64.lib not found"

  • Ensure X-Plane SDK is in lib/SDK/Libraries/Win/
  • Check that you're building for x64 platform
  • Verify Visual Studio is configured for 64-bit builds

Windows: "Cannot open include file 'mavlink/mavlink.h'"

# Initialize git submodules
git submodule update --init --recursive

Windows: Build fails with "MSB8066: Custom build exited with code 1"

  • Close Visual Studio
  • Delete build/ folder
  • Reopen Visual Studio and rebuild

macOS/Linux: "Compiler not found"

# Check if compiler is installed
which g++     # Linux
which clang++  # macOS

# Install build tools (see Prerequisites section)

macOS/Linux: "X-Plane SDK not found"

  • Ensure lib/SDK/ directory exists and contains X-Plane SDK files
  • The SDK should have been included with the project

macOS/Linux: "MAVLink library not found"

# Initialize git submodules
git submodule update --init --recursive

Permission denied during build

# Make sure you have write permissions
chmod +w .
# Or run from a directory you own

Runtime Issues

Plugin not loading in X-Plane:

  1. Check X-Plane's Log.txt file for errors:

    • Windows: Documents/X-Plane 12/Log.txt
    • macOS: ~/Desktop/X-Plane 12/Log.txt
    • Linux: ~/X-Plane 12/Log.txt

  2. Verify plugin location and files. Use the same layout under X-Plane 11/Resources/plugins/px4xplane/ if you are using X-Plane 11.

    X-Plane 12/Resources/plugins/px4xplane/
├── 64/
│   └── win.xpl (or lin.xpl or mac.xpl)
├── config.ini      # ✓ Must be present
└── README.md

  3. Check file permissions (macOS/Linux):

    chmod +x /path/to/xplane/Resources/plugins/px4xplane/64/*.xpl

  4. Windows: Missing Visual C++ Redistributable:

Connection issues with PX4:

  1. Check firewall settings (ports 14560, 14580)
  2. Verify PX4 SITL is running
  3. Check configuration in config.ini

Debug Build

For debugging, use the debug configuration:

Windows:

  • Select "Debug" configuration in Visual Studio
  • Build the project
  • Use Visual Studio debugger or attach to X-Plane process

macOS/Linux:

make debug

Debug builds include:

  • Debug symbols for GDB/LLDB/Visual Studio
  • No optimization (easier debugging)
  • Additional runtime checks
  • Detailed logging

Getting Help

Display build information:

make info

Check dependencies:

make check-deps

Show all available commands:

make help

Development

Code Organization

  • src/: All C++ source files
  • include/: Header files
  • lib/: External dependencies
  • config/: Configuration files

Development Workflow

Windows (Visual Studio)

  1. Make changes to source code in Visual Studio
  2. Build debug version:
    • Select "Debug" configuration
    • Press Ctrl+Shift+B or Build → Build Solution
  3. Test in X-Plane
  4. Debug using Visual Studio:
    • Set breakpoints in source code
    • Debug → Attach to Process → Select X-Plane
    • Or launch X-Plane from Visual Studio debugger
  5. Build release when ready:
    • Select "Release" configuration
    • Build → Build Solution

macOS/Linux (Makefile)

  1. Make changes to source code
  2. Build debug version: 
    make debug
  3. Test in X-Plane
  4. Debug if needed using GDB/LLDB: 
    # Attach to running X-Plane process
gdb -p $(pidof X-Plane)
# Or use LLDB on macOS
lldb -p $(pgrep X-Plane)
  5. Build release when ready: 
    make release

Adding New Source Files

Windows (Visual Studio)

  1. Add source file (.cpp):

    • Right-click project in Solution Explorer
    • Add → New Item → C++ File (.cpp)
    • Or Add → Existing Item to add existing file

  2. Add header file (.h):

    • Right-click project in Solution Explorer
    • Add → New Item → Header File (.h)

  3. Rebuild:

    • Build → Rebuild Solution

macOS/Linux (Makefile)

If you add new .cpp files:

  1. Add the file path to SOURCES in the Makefile:

    SOURCES := \
    src/ConfigManager.cpp \
    src/configReader.cpp \
    # ... existing files ...
    src/YourNewFile.cpp

  2. Rebuild:

    make clean && make

Performance Tips

  • Windows: Use "Release" configuration for final testing (significant performance improvement)
  • All platforms: Use parallel builds:
    • Windows: Build → Build Solution uses multiple cores automatically
    • macOS/Linux: make -j$(nproc) or make -j$(sysctl -n hw.ncpu)
  • Use debug configuration only during development

Best Practices

  1. Always clean before important builds:

    • Windows: Build → Clean Solution, then Build → Rebuild Solution
    • macOS/Linux: make clean && make

  2. Test both configurations: debug for development, release for final testing

  3. Version control:

    • Commit working code before major changes
    • Don't commit build artifacts (build/ folders)
    • Keep submodules updated: git submodule update --remote

  4. Cross-platform compatibility:

    • Test on target platforms when possible
    • Use relative paths in code
    • Follow C++17 standards

  5. Plugin installation:

    • Always test in clean X-Plane installation
    • Verify plugin loads in X-Plane's Plugin Admin
    • Check Log.txt for any warnings or errors

Continuous Integration

For automated builds across platforms, the project includes:

  • Windows: Visual Studio project files
  • macOS/Linux: Professional Makefiles
  • Cross-platform: Git submodules for dependencies

Platform-Specific Notes

Windows:

  • Output: win.xpl (64-bit only)
  • Dependencies handled automatically by Visual Studio
  • Use Windows-style paths in file operations

macOS:

  • Output: mac.xpl (Universal or x86_64)
  • Framework-based X-Plane SDK linking
  • Use Unix-style paths

Linux:

  • Output: linux.xpl (x86_64)
  • Shared library-based X-Plane SDK linking
  • Use Unix-style paths

Version Information

  • Build System Version: 4.2.1
  • Supported Platforms:
    • Windows 10+ (Visual Studio 2019/2022, MinGW)
    • macOS 10.14+ (Xcode Command Line Tools, Universal Binary support)
    • Linux (Ubuntu 18.04+, CentOS 7+, Fedora, Arch)
  • Build Methods:
    • CMake: Unified cross-platform (Recommended)
    • Visual Studio: Windows IDE/MSBuild
    • Native Makefiles: Makefile.linux, Makefile.macos
  • C++ Standard: C++17
  • X-Plane SDK: Latest version included (4.0.0+)
  • Plugin Version: 4.2.1
  • Repository: alireza787b/px4xplane

Additional Resources

Need Help?

  • Check the troubleshooting section above
  • Run make help for quick reference
  • Review X-Plane's Log.txt for runtime issues