From 50a1b0f579fc695db87d76df099e4ef49c5411c6 Mon Sep 17 00:00:00 2001 From: SatoMew Date: Thu, 21 May 2020 15:29:48 +0100 Subject: Clean up, include feedback, and update INSTALL.md --- INSTALL.md | 61 ++++++++++++++++++++++++++++++++----------------------------- 1 file changed, 32 insertions(+), 29 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index c2d3f32da..282f2cd81 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,23 +1,26 @@ # Prerequisites -| Linux | macOS | Windows 10 (build 18917+) | Windows 10 (1709+) | Windows Vista, 7, 8, 8.1, and 10 (1507, 1511, 1607, and 1703) -| ----- | ----- | ------------------------- | ------------------ | --------------------------------------------------------- -| none | [Xcode Command Line Tools package][xcode] | [Windows Subsystem for Linux 2][wsl2] | [Windows Subsystem for Linux][wsl] | MSYS2 (see below) +| Linux | macOS | Windows 10 +| - | - | - +| none | [Xcode Command Line Tools Package][xcode] | [Windows Terminal][terminal] and [Windows Subsystem for Linux (WSL)][wsl] -[xcode]: https://developer.apple.com/library/archive/technotes/tn2339/_index.html#//apple_ref/doc/uid/DTS40014588-CH1-DOWNLOADING_COMMAND_LINE_TOOLS_IS_NOT_AVAILABLE_IN_XCODE_FOR_MACOS_10_9__HOW_CAN_I_INSTALL_THEM_ON_MY_MACHINE_ -[wsl2]: https://docs.microsoft.com/windows/wsl/wsl2-install +[xcode]: https://developer.apple.com/library/archive/technotes/tn2339/_index.html +[terminal]: https://docs.microsoft.com/windows/terminal/get-started [wsl]: https://docs.microsoft.com/windows/wsl/install-win10 -The [prerelease version of the Linux subsystem](https://docs.microsoft.com/windows/wsl/install-legacy) available in the 1607 and 1703 releases of Windows 10 is obsolete so consider uninstalling it. +Make sure that the `gcc`, `g++`, `make`, `git`, and `libpng` packages or their equivalents are installed. The package names and installation methods vary with each OS. -Make sure that the `build-essential`, `git`, and `libpng-dev` packages are installed. The `build-essential` package includes the `make`, `gcc-core`, and `g++` packages so they do not have to be obtained separately. MSYS2 does not include `libpng-dev` so it must be built from source. +Install the devkitARM toolchain of devkitPro as per [the instructions on their wiki](https://devkitpro.org/wiki/devkitPro_pacman). On Windows, WSL is the development environment, thus any steps about the Windows installer do not apply. -Install the **devkitARM** toolchain of [devkitPro](https://devkitpro.org/wiki/Getting_Started) and add its environment variables. For Windows versions without the Linux subsystem, the devkitPro [graphical installer](https://github.com/devkitPro/installer/releases) includes a preconfigured MSYS2 environment, thus the steps below are not required. +The following tools are necessary depending on your needs: - export DEVKITPRO=/opt/devkitPro - echo "export DEVKITPRO=$DEVKITPRO" >> ~/.bashrc - export DEVKITARM=$DEVKITPRO/devkitARM - echo "export DEVKITARM=$DEVKITARM" >> ~/.bashrc +* [porymap](https://github.com/huderlem/porymap) for viewing and editing maps +* [poryscript](https://github.com/huderlem/poryscript) for scripting ([VS Code extension](https://marketplace.visualstudio.com/items?itemName=karathan.poryscript)) +* [Tilemap Studio](https://github.com/Rangi42/tilemap-studio) for viewing and editing tilemaps + +**Windows 10 users:** WSL 2 is included starting in the 2004 release (build 19041) and will eventually become [the default for new installations](https://devblogs.microsoft.com/commandline/the-windows-subsystem-for-linux-build-2020-summary/#wsl2-default), therefore existing WSL 1 and [prerelease WSL](https://docs.microsoft.com/windows/wsl/install-legacy) users are recommended to update. Right-click the Start button and choose System to determine the Windows version. + +**Windows 7 and 8.1 users:** pret is no longer focusing on support in pokeemerald for [old versions of Windows](https://support.microsoft.com/help/13853) so consider upgrading to a current release of Windows 10 or try a third-party guide like [this one](https://www.pokecommunity.com/showthread.php?t=425246) instead. # Installation @@ -33,22 +36,25 @@ To set up the repository: cd ../pokeemerald -To build **pokeemerald.gba** and confirm it matches the official ROM image: +To build **pokeemerald.gba** for the first time and confirm it matches the official ROM image: make compare -## Notes +If an OK is returned, then the installation went smoothly. -* If the base tools are not found on macOS in new Terminal sessions after the first successful build, run `echo "if [ -f ~/.bashrc ]; then . ~/.bashrc; fi" >> ~/.bash_profile` once to prevent the issue from occurring again. Verify that the `devkitarm-rules` package is installed as well; if not, install it by running `sudo dkp-pacman -S devkitarm-rules`. -* If the repository was previously set up using Cygwin, delete the `.exe` files in the subfolders of the `tools` folder except for `agbcc` and try building again. [Learn the differences between MSYS2 and Cygwin.](https://github.com/msys2/msys2/wiki/How-does-MSYS2-differ-from-Cygwin) - -# Guidance +# Start To build **pokeemerald.gba** with your changes: make +**macOS users:** If the base tools are not found in new Terminal sessions after the first successful build, run `echo "if [ -f ~/.bashrc ]; then . ~/.bashrc; fi" >> ~/.bash_profile` once to prevent the issue from occurring again. Verify that the `devkitarm-rules` package is installed as well; if not, install it by running `sudo dkp-pacman -S devkitarm-rules`. + + +# Building guidance + + ## Parallel builds See [the GNU docs](https://www.gnu.org/software/make/manual/html_node/Parallel.html) and [this Stack Exchange thread](https://unix.stackexchange.com/questions/208568) for more information. @@ -59,19 +65,22 @@ To speed up building, run: `nproc` is not available on macOS. The alternative is `sysctl -n hw.ncpu` ([relevant Stack Overflow thread](https://stackoverflow.com/questions/1715580)). -## Building without dependency scanning -If only `.c` or `.s` files were changed, turn off the dependency scanning temporarily. Changes to any other files will be ignored and the build will either fail or not reflect those changes. +## Debug info - make NODEP=1 +To build **pokeemerald.elf** with enhanced debug info: -## Building with devkitARM's C compiler + make DINFO=1 + + +## devkitARM's C compiler This project supports the `arm-none-eabi-gcc` compiler included with devkitARM r52. To build this target, simply run: make modern -## Building with other toolchains + +## Other toolchains To build using a toolchain other than devkitARM, override the `TOOLCHAIN` environment variable with the path to your toolchain, which must contain the subdirectory `bin`. @@ -82,9 +91,3 @@ The following is an example: make TOOLCHAIN="/usr/local/arm-none-eabi" To compile the `modern` target with this toolchain, the subdirectories `lib`, `include`, and `arm-none-eabi` must also be present. - -## Building with debug info - -To build **pokeemerald.elf** with enhanced debug info, use the `DINFO` variable. - - make DINFO=1 -- cgit v1.2.3 From a42ac3ae07a20103a245ed0b34081d62972d7914 Mon Sep 17 00:00:00 2001 From: SatoMew Date: Fri, 28 Aug 2020 23:10:58 +0100 Subject: Improved based on feedback and recent changes --- INSTALL.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 282f2cd81..2865c2c42 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,24 +1,20 @@ # Prerequisites -| Linux | macOS | Windows 10 -| - | - | - -| none | [Xcode Command Line Tools Package][xcode] | [Windows Terminal][terminal] and [Windows Subsystem for Linux (WSL)][wsl] +| macOS | Windows 10 +| - | - +| [Xcode Command Line Tools Package][xcode] | [Windows Terminal][terminal] and [Windows Subsystem for Linux (WSL)][wsl] [xcode]: https://developer.apple.com/library/archive/technotes/tn2339/_index.html [terminal]: https://docs.microsoft.com/windows/terminal/get-started [wsl]: https://docs.microsoft.com/windows/wsl/install-win10 -Make sure that the `gcc`, `g++`, `make`, `git`, and `libpng` packages or their equivalents are installed. The package names and installation methods vary with each OS. +Independently from the specific OS, make sure that the `gcc`, `g++`, `make`, `git`, and `libpng` packages or their equivalents are installed and accessible to the development tools that are used by the project (this means that, for example, on Windows, the packages have to be installed in the WSL environment). The package names and installation methods may vary with each OS. -Install the devkitARM toolchain of devkitPro as per [the instructions on their wiki](https://devkitpro.org/wiki/devkitPro_pacman). On Windows, WSL is the development environment, thus any steps about the Windows installer do not apply. +Install the devkitARM toolchain of devkitPro as per [the instructions on their wiki](https://devkitpro.org/wiki/devkitPro_pacman). On Windows, follow the Linux instructions inside WSL as any steps about the Windows installer do not apply. -The following tools are necessary depending on your needs: +**Debian-based distro users:** This applies if you use Debian, Ubuntu, and similar distros, including in WSL. If necessary, install the `libarchive13`, `pkg-config`, and `gdebi-core` packages to be able to install devkitPro. -* [porymap](https://github.com/huderlem/porymap) for viewing and editing maps -* [poryscript](https://github.com/huderlem/poryscript) for scripting ([VS Code extension](https://marketplace.visualstudio.com/items?itemName=karathan.poryscript)) -* [Tilemap Studio](https://github.com/Rangi42/tilemap-studio) for viewing and editing tilemaps - -**Windows 10 users:** WSL 2 is included starting in the 2004 release (build 19041) and will eventually become [the default for new installations](https://devblogs.microsoft.com/commandline/the-windows-subsystem-for-linux-build-2020-summary/#wsl2-default), therefore existing WSL 1 and [prerelease WSL](https://docs.microsoft.com/windows/wsl/install-legacy) users are recommended to update. Right-click the Start button and choose System to determine the Windows version. +**Windows 10 users:** WSL 2 is available in the 1903 release (build 18362) and later, therefore existing WSL 1 and [prerelease WSL](https://docs.microsoft.com/windows/wsl/install-legacy) users are recommended to update. Right-click the Start button or press `Win`+`X` and choose System to determine the Windows version. Also check Windows Update to make sure your installation is up-to-date. **Windows 7 and 8.1 users:** pret is no longer focusing on support in pokeemerald for [old versions of Windows](https://support.microsoft.com/help/13853) so consider upgrading to a current release of Windows 10 or try a third-party guide like [this one](https://www.pokecommunity.com/showthread.php?t=425246) instead. @@ -91,3 +87,10 @@ The following is an example: make TOOLCHAIN="/usr/local/arm-none-eabi" To compile the `modern` target with this toolchain, the subdirectories `lib`, `include`, and `arm-none-eabi` must also be present. + + +# Useful additional tools + +* [porymap](https://github.com/huderlem/porymap) for viewing and editing maps +* [poryscript](https://github.com/huderlem/poryscript) for scripting ([VS Code extension](https://marketplace.visualstudio.com/items?itemName=karathan.poryscript)) +* [Tilemap Studio](https://github.com/Rangi42/tilemap-studio) for viewing and editing tilemaps -- cgit v1.2.3 From fc277025d60051ca7c6af64b8a96f2317620536e Mon Sep 17 00:00:00 2001 From: SatoMew Date: Fri, 28 Aug 2020 23:37:17 +0100 Subject: Added better instructions for checking Winver --- INSTALL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/INSTALL.md b/INSTALL.md index 2865c2c42..7256a45d2 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -14,7 +14,7 @@ Install the devkitARM toolchain of devkitPro as per [the instructions on their w **Debian-based distro users:** This applies if you use Debian, Ubuntu, and similar distros, including in WSL. If necessary, install the `libarchive13`, `pkg-config`, and `gdebi-core` packages to be able to install devkitPro. -**Windows 10 users:** WSL 2 is available in the 1903 release (build 18362) and later, therefore existing WSL 1 and [prerelease WSL](https://docs.microsoft.com/windows/wsl/install-legacy) users are recommended to update. Right-click the Start button or press `Win`+`X` and choose System to determine the Windows version. Also check Windows Update to make sure your installation is up-to-date. +**Windows 10 users:** WSL 2 is available in the 1903 release (build 18362) and later, therefore existing WSL 1 and [prerelease WSL](https://docs.microsoft.com/windows/wsl/install-legacy) users are recommended to update. Right-click the Start button or press `Win`+`X`, choose Run, and run `ms-settings:about` to determine the Windows version. Also check Windows Update to make sure your installation is up-to-date. **Windows 7 and 8.1 users:** pret is no longer focusing on support in pokeemerald for [old versions of Windows](https://support.microsoft.com/help/13853) so consider upgrading to a current release of Windows 10 or try a third-party guide like [this one](https://www.pokecommunity.com/showthread.php?t=425246) instead. -- cgit v1.2.3 From ece8d68be1b5bf1c6087d39d6d372b7b83026b43 Mon Sep 17 00:00:00 2001 From: SatoMew Date: Sat, 29 Aug 2020 10:22:25 +0100 Subject: Added the Linux column back --- INSTALL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 7256a45d2..9f862a8cb 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,8 +1,8 @@ # Prerequisites -| macOS | Windows 10 -| - | - -| [Xcode Command Line Tools Package][xcode] | [Windows Terminal][terminal] and [Windows Subsystem for Linux (WSL)][wsl] +| Linux | macOS | Windows 10 +| - | - | - +| none | [Xcode Command Line Tools Package][xcode] | [Windows Terminal][terminal] and [Windows Subsystem for Linux (WSL)][wsl] [xcode]: https://developer.apple.com/library/archive/technotes/tn2339/_index.html [terminal]: https://docs.microsoft.com/windows/terminal/get-started -- cgit v1.2.3 From bc79971308189ed648f7137daa511b79ee238c09 Mon Sep 17 00:00:00 2001 From: SatoMew Date: Sat, 29 Aug 2020 12:33:11 +0100 Subject: Update INSTALL.md --- INSTALL.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/INSTALL.md b/INSTALL.md index 9f862a8cb..f16384450 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -12,7 +12,7 @@ Independently from the specific OS, make sure that the `gcc`, `g++`, `make`, `gi Install the devkitARM toolchain of devkitPro as per [the instructions on their wiki](https://devkitpro.org/wiki/devkitPro_pacman). On Windows, follow the Linux instructions inside WSL as any steps about the Windows installer do not apply. -**Debian-based distro users:** This applies if you use Debian, Ubuntu, and similar distros, including in WSL. If necessary, install the `libarchive13`, `pkg-config`, and `gdebi-core` packages to be able to install devkitPro. +**Debian-based distro users:** This applies to Debian, Ubuntu, and similar distros, including in WSL. If necessary, install the `libarchive13`, `pkg-config`, and `gdebi-core` packages to be able to install devkitPro. **Windows 10 users:** WSL 2 is available in the 1903 release (build 18362) and later, therefore existing WSL 1 and [prerelease WSL](https://docs.microsoft.com/windows/wsl/install-legacy) users are recommended to update. Right-click the Start button or press `Win`+`X`, choose Run, and run `ms-settings:about` to determine the Windows version. Also check Windows Update to make sure your installation is up-to-date. @@ -38,6 +38,8 @@ To build **pokeemerald.gba** for the first time and confirm it matches the offic If an OK is returned, then the installation went smoothly. +**Windows users:** Consider adding exceptions for the `pokeemerald` and `agbcc` folders in Windows Security using [these instructions](https://support.microsoft.com/help/4028485). This prevents Microsoft Defender from scanning them which might improve performance while building. + # Start -- cgit v1.2.3