diff --git a/README.md b/README.md index 4ee5c747fd1be356d773c0aad48d6c604a4d3a8b..8c78ce8d05bcde9c4be8d57f53a32f62022df5f7 100644 --- a/README.md +++ b/README.md @@ -2,111 +2,116 @@ recalbox ======== ![](https://s3-eu-west-1.amazonaws.com/forums.recalbox.com/8d81e556-aefb-4729-ad2f-9d7386eff4cd.png) -Welcome to the main recalbox repository. +Welcome to the main recalbox repository! -This repository contains the source code that builds recalbox for different boards. +Recalbox is an open-source operating system built for emulation. It provides an accessible, user-friendly platform to run classic games on a wide range of hardware devices. Designed with ease of use and performance in mind, Recalbox is perfect for retro gaming enthusiasts and developers interested in exploring advanced emulation technology. Contributions from the community are always welcome to help improve and expand this dynamic project. -Recalbox is an opensource project. We hope that you will contribute and help us to improve this OS. -But if you are working on a fork, by respect for our work, we ask you not to integrate our work in progress located on branches other than master. -Thank you for waiting for a merge on master branch. +This repository contains the complete source code needed to build Recalbox for various boards. Organized as a monorepo, all related components are housed together. This structure allows coordinated changes across different parts of the system (such as Buildroot, EmulationStation, and Configgen) in a single merge request, with our pipeline testing every component before building the final image. -NEW : we integrated external projects in this repository. Recalbox is now a monorepo. That means: -- you can make changes to every part of recalbox (buildroot, frontend, configgen...) in a single merge request -- the pipeline now test every projects before building -- reference commits are no longer needed in `packages.mk` +Recalbox is an open-source project. We hope that you will contribute and help us improve this OS. However, if you are working on a fork, by respect for our work, please do not integrate our work-in-progress branches other than master. Wait for an official merge into the master branch before pulling changes. -Please use [**Issues**](https://gitlab.com/recalbox/recalbox/-/issues) to report a bug or request a feature. +Please use [**Issues**](https://gitlab.com/recalbox/recalbox/-/issues) to report bugs or request new features. + +NEW: We have integrated external projects into this repository, transforming Recalbox into a comprehensive monorepo. This means: +- You can make changes to every part of Recalbox (buildroot, frontend, configgen, etc.) in a single merge request. +- The build pipeline now tests every project before building, ensuring better quality and stability. +- Reference commits are no longer needed in `packages.mk`, streamlining our development process. ## Recalbox Projects -- [recalbox](https://gitlab.com/recalbox/recalbox): the repository contains the source code to build recalbox. -- [emulationstation](./projects/frontend/): the emulationstation frontend for recalbox. -- [configgen](./projects/frontend/): the tool for automatic joystick configuration. -- [recalbox-hardware](./projects/recalbox-hardware/): managing case and several hardwares for recalbox. -- [recalbox-rgb-dual](./projects/recalbox-rgb-dual/): Recalbox RGB Dual project with DT and kernel module. -- [wpaf](./projects/wpaf/): fan manager. -- [piboy](./projects/piboy/): piboy dmg detector. +- **recalbox**: [recalbox](https://gitlab.com/recalbox/recalbox) + This is the core repository containing the source code to build the Recalbox operating system. It includes all essential components required for emulation and system management. -## Useful links -- [www.recalbox.com](https://www.recalbox.com): the official recalbox website. -- [Recalbox Wiki](https://wiki.recalbox.com) the wiki of recalbox. -- [forum.recalbox.com](https://forum.recalbox.com): recalbox forum. You will find support there. +- **emulationstation**: [emulationstation](./projects/frontend/) + The frontend interface for Recalbox, EmulationStation provides an intuitive way to browse and launch games. It is designed to be both visually appealing and highly customizable, catering to a variety of gaming setups. +- **configgen**: [configgen](./projects/frontend/) + This tool automates the configuration of joysticks and controllers, making it easier for users to set up their input devices without manual intervention. -# How to build (Linux only) ![Build status](https://gitlab.com/recalbox/recalbox/badges/master/pipeline.svg?style=flat-square) +- **recalbox-hardware**: [recalbox-hardware](./projects/recalbox-hardware/) + This component manages hardware-specific configurations and drivers, ensuring that Recalbox runs smoothly on a wide range of devices and peripherals. -### General steps +- **recalbox-rgb-dual**: [recalbox-rgb-dual](./projects/recalbox-rgb-dual/) + Supports dual display setups through Device Tree integration and custom kernel modules, enhancing the gaming experience on systems that support multiple screens. -Install docker: [docs.docker.com/install/](https://docs.docker.com/install/) +- **wpaf**: [wpaf](./projects/wpaf/) + Responsible for fan management, this project ensures optimal system cooling by dynamically controlling the fan speed based on system temperature. -Make sure your user belongs to the docker group -> `sudo usermod -a -G docker $USER` then logoff/login +- **piboy**: [piboy](./projects/piboy/) + Detects and configures Piboy DMG hardware, enabling specialized support for this device to ensure all features work correctly. -Clone the repository: +## Useful links -```bash -ARCH="rpi4" && git clone https://gitlab.com/recalbox/recalbox.git recalbox-${ARCH} -``` +- [www.recalbox.com](https://www.recalbox.com): The official Recalbox website, offering downloads, news, and community resources. +- [Recalbox Wiki](https://wiki.recalbox.com): A comprehensive resource with documentation, guides, and FAQs. +- [forum.recalbox.com](https://forum.recalbox.com): The Recalbox forum, where users can get support, share tips, and discuss new features. -**Build** recalbox: +# How to build (Linux only) ![Build status](https://gitlab.com/recalbox/recalbox/badges/master/pipeline.svg?style=flat-square) -```bash -export ARCH="rpi4" -cd recalbox-${ARCH} -./scripts/linux/recaldocker.sh -``` +Recalbox currently supports building on Linux. Follow the steps below to compile Recalbox for your preferred board. -The build time depends on the CPU power of your computer, and will produce a Recalbox image for the architecture specified in `ARCH` variable. +### General steps -At the end of the build, the image will be available in `output/images/recalbox/`. +1. **Install Docker** + Visit [docs.docker.com/install/](https://docs.docker.com/install/) to install Docker for your system. After installation, make sure your user belongs to the `docker` group: + ```bash + sudo usermod -a -G docker $USER + ``` + Log off and log back in for the changes to take effect. + +2. **Clone the repository** + ```bash + ARCH="rpi4" && git clone https://gitlab.com/recalbox/recalbox.git recalbox-${ARCH} + ``` + Replace `rpi4` with your target architecture if needed. + +3. **Build Recalbox** + ```bash + export ARCH="rpi4" + cd recalbox-${ARCH} + ./scripts/linux/recaldocker.sh + ``` + The build process depends on your CPU power. When it finishes, you will find the resulting Recalbox image in `output/images/recalbox/`. ### Customize build You can set the following environment variables to customize the build: -* `ARCH`: to force the target architecture (see available architectures in the [`configs` directory](configs), default is to infer it from the current directory name) -* `RECALBOX_VERSION`: to set a Recalbox build version (no impact on build, just the version shown) -* `PACKAGE`: if you want to build a single package +- `ARCH`: Forces the target architecture (see available architectures in the [`configs`](configs) directory). If not set, the script attempts to infer the architecture from your directory name. +- `RECALBOX_VERSION`: Sets the build version number (for display purposes only). +- `PACKAGE`: Builds a single package instead of the entire system. -In the recalbox directory, you will find some directories created by the build: -* `host` folder that contains output compiled for your host -* `dl` folder that contains all packages download -* `output` folder that contains compiled files +After building, you will see several directories in your `recalbox-${ARCH}` folder: +- `host`: Contains output compiled for your host machine. +- `dl`: Stores downloaded packages. +- `output`: Contains all compiled files (including your final Recalbox image). ### Custom command and menuconfig -Using the command line arguments, you can pass a custom command to run: +You can pass custom commands through the build script. For example: ```bash ARCH=rpi4 && ./scripts/linux/recaldocker.sh make menuconfig ``` - -This way you can run menuconfig to configure the system. If you never built the system, use the following command to create the default configuration for your board: +This allows you to run `menuconfig` and modify system options before compiling. If you have never built Recalbox before, set up the default configuration for your board: ```bash ARCH=rpi4 && ./scripts/linux/recaldocker.sh make "recalbox-${ARCH}_defconfig" && make menuconfig ``` - -Your command will override the default build command from the docker image, so you may have to copy past some variable from it. +Remember that your custom command overrides the default build command, so you may need to copy relevant variables from the script. ### Known issues -The docker build process only works on `linux`. - -During the image built if you encounter errors like the following : - -```text -Reading package lists... +The Docker build process works only on Linux. If you encounter DNS-related errors such as: +``` W: Failed to fetch http://archive.ubuntu.com/ubuntu/dists/xenial/InRelease Temporary failure resolving 'archive.ubuntu.com' -W: Failed to fetch http://archive.ubuntu.com/ubuntu/dists/xenial-updates/InRelease Temporary failure resolving 'archive.ubuntu.com' -W: Failed to fetch http://archive.ubuntu.com/ubuntu/dists/xenial-backports/InRelease Temporary failure resolving 'archive.ubuntu.com' -W: Failed to fetch http://security.ubuntu.com/ubuntu/dists/xenial-security/InRelease Temporary failure resolving 'security.ubuntu.com' -W: Some index files failed to download. They have been ignored, or old ones used instead. ``` -Docker cannot access to internet to make updates. More precisely, it is a DNS problem (see https://odino.org/cannot-connect-to-the-internet-from-your-docker-containers/). If your `/etc/resolv.conf` is empty (it happens if all is managed by `network-manager` for example), Docker does not know which DNS to use. You'll need to tell him through the `/etc/default/docker` file by adding this line : - -```text +it typically means Docker cannot resolve DNS entries. If `/etc/resolv.conf` is empty (often when everything is managed by `network-manager`), Docker may not know which DNS to use. Fix it by adding a DNS server in `/etc/default/docker`: +``` DOCKER_OPTS="--dns IP.OF.YOUR.DNS" ``` -Restart Docker and retry. It should be ok. - +Replace `IP.OF.YOUR.DNS` with your actual DNS server address. Then restart Docker: ```bash sudo service docker restart -docker build -t "recalbox-dev" . ``` +After that, try building again. +```bash +docker build -t "recalbox-dev" . +``` \ No newline at end of file