Skip to content

AGENTS.md

Latest commit

 

History

History
107 lines (72 loc) · 4.55 KB

AGENTS.md

File metadata and controls

107 lines (72 loc) · 4.55 KB

Brief overview

These are general guidelines for working in this workspace.

Communication style

  • Be direct and concise in your responses.
  • Provide clear explanations for your actions.

Development workflow

  • Use the docs/ directory for all documentation.
  • Follow the existing structure of the project when adding new files.
  • Use the Makefile to build the project.

Coding best practices

  • Follow the coding style of the existing code.
  • Write tests for new features.

Project context

Contribution Areas

  • Compiler: Work on the CPython compilation to WebAssembly, including LLVM and Emscripten.
  • Python: Improve the Python interpreter, including standard library compatibility, performance, and size.
  • Package Support: Add support for new packages, including those with C, C++, Fortran, or Rust extensions.
  • Packaging and Distribution: Improve the packaging and distribution of Pyodide and its packages.
  • Browser Integration: Enhance the interaction between the Python and JavaScript runtimes.
  • JS Runtimes: Improve support for different JavaScript runtimes, such as Node.js, Deno, and Bun.
  • Tooling: Improve the build system, package installer, and testing infrastructure.
  • Documentation: Improve the existing documentation and add new content.
  • Application Development: Build new applications using Pyodide.

Development Environment

  • The development environment is Linux-based.
  • For Windows users, WSL or GitHub Codespaces is recommended.
  • Follow the instructions in the documentation to build Pyodide from source.

Project Structure

  • cpython/: Contains the CPython source code, patches, and build scripts.
  • src/: Contains the JavaScript and Python APIs, as well as the Foreign Function Interface (FFI).
  • packages/: Contains the recipes for building Python packages.
  • pyodide-build/: Contains the build system for Pyodide. pyodide-build is a submodule and we do not directly modify the source code in this repository. All the pyodide-build-related changes should be dealt separately in pyodide-build repository.

Key Technologies

  • WebAssembly: The compilation target for the CPython interpreter and native extensions.
  • Emscripten: The compiler toolchain used to build WebAssembly modules for the browser.
  • LLVM: The underlying compiler infrastructure used by Emscripten.

Building the project

  • Use make to build the project.
  • For a streamlined build process, use the provided Docker image.
  • When building from source, follow the specific instructions for your operating system (Linux, macOS).

Package Management

  • Python packages are built using recipes defined in meta.yaml files.
  • To add a new package, create a recipe and add it to the pyodide-recipes repository.
  • Use pyodide build to build individual packages from source.

Contributing

  • Follow the development workflow outlined in docs/development/contributing.md.
  • Adhere to the Code of Conduct.
  • Use prek (faster alternative to pre-commit) to ensure code style consistency.

Core C Code Development

  • When modifying the core C code in src/core, follow the guidelines in docs/development/core.md.
  • Use the provided error handling macros for consistency.
  • Follow the specified function structure for clarity and correct resource management.

Testing and Debugging

  • Use pytest for the Python test suite and npm test for the JavaScript tests.
  • Refer to docs/development/debugging.md for tips on debugging, including how to handle linker errors and build with symbols.

Documentation Structure

  • All documentation is located in the docs/ directory.
  • The documentation is organized into three main sections: usage, development, and project.
  • New documentation should be added to the appropriate section.

Tooling and Dependencies

  • The documentation is built using Sphinx.
  • The required Python packages for building the documentation are listed in docs/requirements-doc.txt.
  • When adding new dependencies, update docs/requirements-doc.txt.

Content and Style

  • The main entry point for the documentation is docs/index.rst.
  • We only use markdown except for the index.rst file.
  • JavaScript and TypeScript documentation is handled via sphinx-js.

Building the Documentation

  • The Makefile and make.bat files in the docs/ directory are used to build the documentation.
  • Use make help to see available build targets.