Call for Contributors: Help Bring Ciyue to macOS! 🚀

[mumu-lhl]

Currently, Ciyue does not support macOS. As the developer, I do not use macOS daily, nor do I have hardware with sufficient performance to run a macOS virtual machine effectively for development and testing.

However, we believe adding macOS support should be a relatively straightforward task for someone with the right setup, thanks to Flutter! If you have a Mac and are looking to contribute, we'd love your help.

This guide provides a starting point. If you encounter issues, searching for the error message or asking AI tools (like Deepseek, Gemini, ChatGPT, etc.) can often provide solutions.

Prerequisites

Before starting, please ensure you have the following installed:

• A macOS machine (or capable VM).
• Xcode (and its command-line tools)
• Flutter (ensure desktop support is enabled: flutter config --enable-macos-desktop)
• git

Contribution Guide

Follow these steps to get started:

1. Clone the Repository

Open your terminal and run:

# Clone the project and enter the directory
git clone https://github.com/mumu-lhl/Ciyue.git && cd Ciyue 

(Note: A common workflow is to Fork the repository on GitHub first, then clone your fork).

2. Create a New Branch

Create and switch to a dedicated branch for your work:

 git switch -c feat/macos

3. Get Dependencies

Ensure all packages are downloaded:

flutter pub get

4. Build and Troubleshoot

There are two main areas to check:

• Native macOS Code:

  • Open the project's macOS runner in Xcode: open macos/Runner.xcworkspace.
  • Try building the project within Xcode (Product -> Build).
  • You will likely encounter errors related to build settings, signing, capabilities (e.g., App Sandbox, network/file access entitlements), or plugins that lack macOS support. Fix these errors based on the Xcode output.

• Flutter/Dart Code:

  • Try running directly: flutter run -d macos
  • Search the codebase for platform-specific checks. Where logic applies to desktop platforms generally, add Platform.isMacOS.

  For example:

  // Before:
  } else if (Platform.isWindows) { 
     // desktop-specific code
  
  // After:
   } else if (Platform.isWindows || Platform.isMacOS) { // Add check here
      // desktop-specific code

  • Test key features to ensure they function correctly and the UI layout looks appropriate on macOS. Some plugins or features might require a specific if (Platform.isMacOS) block with unique macOS implementation.

5. Commit and Push Your Work

Once the application builds and runs:

git add -A
git commit -m "feat: add initial macOS support"

6. Open a Pull Request

Navigate to the Ciyue GitHub repository and open a new Pull Request, comparing your feat/macos branch against the main branch. Please describe the changes you made and note any issues that might still exist.

Thank You!

This might be your first open-source contribution, or one of many. We sincerely appreciate your time and effort in helping make Ciyue available to more users!