Skip to content
ryu_ldn_nx

Contributing

Contributing

Section titled “Contributing”

Thank you for your interest in contributing to ryu_ldn_nx! This guide will help you get started.

Ways to Contribute

Section titled “Ways to Contribute”
  • Bug Reports — Found an issue? Let us know!
  • Feature Requests — Have an idea? We’d love to hear it!
  • Code — Submit pull requests with fixes or features
  • Documentation — Help improve these docs
  • Testing — Test on different games and configurations

Development Setup

Section titled “Development Setup”

Prerequisites

Section titled “Prerequisites”
  • Docker and Docker Compose
  • Git

Getting Started

Section titled “Getting Started”

  1. Fork the repository

    Terminal window
    git clone --recursive https://github.com/Ethiquema/ryu_ldn_nx.git
    cd ryu_ldn_nx

  2. Build using Docker

    Terminal window
    # Build sysmodule + overlay + dist ZIP
    docker compose run --rm build
    

    # Run tests
    docker compose run --rm test

See Building from Source for detailed build instructions.

Code Structure

Section titled “Code Structure”
ryu_ldn_nx/
├── sysmodule/              # Main sysmodule code
│   └── source/
│       ├── main.cpp        # Entry point, heap, new/delete, service registration
│       ├── config/          # Fixed-buffer INI parser, ConfigManager, ConfigIpcService
│       ├── network/         # TcpClient, Client, ConnectionState, ReconnectManager
│       ├── protocol/        # RyuLdn wire format (types.hpp, ryu_protocol.hpp)
│       ├── ldn/             # LDN MITM service, ICommunicationService, state machine
│       ├── bsd/             # BSD MITM service, ProxySocket, ProxySocketManager
│       ├── p2p/             # P2P proxy client/server, UPnP port mapper
│       └── debug/           # File logger with idle-timeout close thread
├── overlay/                # Tesla overlay (libultrahand)
│   └── source/
│       └── ryu_ldn_ipc.c   # IPC stubs for ryu:cfg service
├── tests/                  # Host unit tests (one .cpp per suite)
├── docs/                   # Astro + Starlight documentation site
├── scripts/
│   ├── builder/            # Build wrapper for parallel docker compose
│   └── debugger/           # GDB presets and component scripts
└── config/                 # Config templates and game whitelist

Coding Standards

Section titled “Coding Standards”

C++ Style

Section titled “C++ Style”
  • C++17 features with Atmosphere conventions
  • 4-space indentation, opening braces on same line
  • Doxygen /** */ doc comments on public API
  • #pragma once for all headers (no include guards)

Naming Conventions

Section titled “Naming Conventions”
  • Namespaces: ams::mitm::ldn, ams::mitm::bsd, ryu_ldn::network, ryu_ldn::protocol, ryu_ldn::config, ryu_ldn::debug, ryu_ldn::ipc
  • Classes and functions: PascalCase (matching Atmosphere style)
  • Variables: snake_case
  • Member variables: m_snake_case
  • Constants: UPPER_SNAKE_CASE or constexpr

Result Patterns

Section titled “Result Patterns”
  • Use ams::Result (Stratosphere Horizon result codes) in sysmodule code
  • Test code uses simple enum class ...Result with Success/...Error

Memory Constraints

Section titled “Memory Constraints”

The sysmodule runs on Switch hardware with aggressive constraints:

  • 384 KB shared heap — no std::vector/std::deque/new in hot paths
  • Use fixed buffers, constinit statics, stack-allocated work areas
  • new/delete route to the expanded heap — do not grow buffers without proof it’s needed

Logging

Section titled “Logging”

Use LOG_ERROR, LOG_WARN, LOG_INFO, LOG_VERBOSE macros from debug/log.hpp.

Platform Guards

Section titled “Platform Guards”
  • #ifdef __SWITCH__ for Switch-specific code
  • Test builds use -DTEST_BUILD and compile with host g++
  • IDE errors for <stratosphere.hpp> and libnx are expected — they compile fine in Docker

Testing

Section titled “Testing”

Running Tests

Section titled “Running Tests”
Terminal window
docker compose run --rm test

Per-Suite Targets

Section titled “Per-Suite Targets”
Terminal window
cd tests && make test-ldn-state-machine
# protocol, config, log, socket, tcp-client, connection-state,
# reconnect, client, ldn-types, ldn-proxy, ldn-error, overlay,
# ipc-config, config-ipc-service, shared-state, packet-dispatcher,
# session-handler, proxy-handler, handler-integration, upnp,
# p2p-proxy, p2p-client, p2p-integration, p2p-create-network

Writing Tests

Section titled “Writing Tests”

Tests use a lightweight custom framework with auto-registration:

TEST(my_feature) {
    MyClass instance;
    auto result = instance.DoSomething();
    ASSERT_TRUE(result == expected);
}

constinit and static_assert in types.hpp are verified at compile time in both test and sysmodule builds.

Pull Request Process

Section titled “Pull Request Process”

  1. Create a branch

    Terminal window
    git checkout -b feature/my-feature

  2. Make your changes

    • Write code
    • Add tests
    • Update documentation

  3. Test locally

    Terminal window
    docker compose run --rm test
    docker compose run --rm build

  4. Commit with DCO sign-off

    Terminal window
    git commit -s -m "feat: add my feature"

  5. Push and create PR

    Terminal window
    git push origin feature/my-feature

DCO Sign-Off

Section titled “DCO Sign-Off”

All commits must be DCO-signed. Use git commit -s so the Signed-off-by: trail comes from your git config automatically.

Terminal window
git commit -s -m "Your commit message"

Rules:

  • Always use git commit -s — never hardcode a developer’s name or email
  • Never add promotional or AI-attribution lines
  • PR checks enforce DCO compliance

Conventional commits format is preferred (feat:, fix:, docs:, refactor:, etc.).

Getting Help

Section titled “Getting Help”