AGENTS.md · pyodide/pyodide

Sections

1. Brief overview
2. Communication style
3. Development workflow
4. Coding best practices
5. Project context
6. Contribution Areas
7. Development Environment
8. Project Structure
9. Key Technologies
10. Building the project
11. Package Management
12. Contributing
13. Core C Code Development
14. Testing and Debugging
15. Documentation Structure
16. Tooling and Dependencies
17. Content and Style
18. Building the Documentation

First lines (shown under the repo's MPL-2.0 license)

## 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

- This project is a Python distribution for the browser and Node.js based on WebAssembly.
- The project is hosted on GitHub at https://github.com/pyodide/pyodide.

## 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.