Skip to content

Comments

Add cross-platform development setup documentation#13

Open
parthdagia05 wants to merge 1 commit intoOSeMOSYS:masterfrom
parthdagia05:docs/add-cross-platform-setup
Open

Add cross-platform development setup documentation#13
parthdagia05 wants to merge 1 commit intoOSeMOSYS:masterfrom
parthdagia05:docs/add-cross-platform-setup

Conversation

@parthdagia05
Copy link

@parthdagia05 parthdagia05 commented Feb 19, 2026

Documentation: Cross-Platform Development & Source Setup Guide

Closes #12

Overview

Currently, the project documentation primarily covers the Windows .exe installation workflow. This PR introduces comprehensive guides for setting up and running MUIO from source on macOS, Linux, and Windows, reducing onboarding friction for new contributors and research teams.


What’s New?

1. Dedicated Development Setup Page

Created docs/source/getting-started/dev-setup.rst which provides step-by-step instructions for:

  • macOS Setup: Homebrew installation for GLPK and CBC (including Apple Silicon paths).
  • Linux/Ubuntu Setup: APT-based installation and dependency management.
  • Windows (Source): Alternative workflow for developers not using the pre-compiled .exe.
  • Environment Configuration: Guidance on using MUIO_GLPK_PATH and MUIO_CBC_PATH environment variables.

2. Technical Deep-Dives

Added documentation for previously "hidden" logic discovered in the codebase:

  • Solver Auto-Discovery: How the system identifies binaries via the system $PATH.
  • Encoding Notes: Guidance on handling the UTF-16LE encoding in requirements.txt.
  • Permissions: Documentation on DATA_STORAGE directory permissions (0o777) required for successful execution.

3. Improved Discoverability

  • Updated docs/source/index.rst to include the new guide in the main Table of Contents.
  • Added a "Development (Run from Source)" section to the root README.md to point users directly to the full documentation.

Impact & Risk

  • Zero Runtime Risk: This PR contains only .rst and .md files. No functional code is modified.
  • Backward Compatibility: Does not affect existing build pipelines or the Windows release workflow.

Checklist

  • Documentation follows the existing Sphinx/RST style.
  • All internal links and toctree references are functional.
  • Verified that the documentation builds locally without warnings.
  • README links point correctly to the new sections.

- Add macOS/Linux/Windows from-source setup guide
- Document solver installation and PATH configuration
- Document requirements.txt encoding behavior
- Document DataStorage permission considerations
- Register page in Getting Started toctree
- Link documentation from README

Refs OSeMOSYS#12
@parthdagia05
Copy link
Author

@VedranKapor can you review this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add cross-platform development setup documentation (macOS/Linux/Windows from source)

1 participant