- **help**: check out the [documentation](doc/README.md), [quick start guide](doc/1-intro/quickstart.md), and [frequently asked questions (FAQ)](doc/1-intro/faq.md).
if you can't download these artifacts (because GitHub requires you to be logged in), [go here](https://nightly.link/tildearrow/furnace/workflows/build/master) instead.
**NOTE: do not download the project's source as a .zip or .tar.gz as these do not include the project's submodules which are necessary to proceed with building. please instead use Git as shown below.**
some Linux distributions (e.g. Ubuntu or openSUSE) will require you to install the `-dev`/`-devel` versions of these.
on Linux, having libintl is recommended for locale support, but if it isn't present, Furnace will use its own implementation.
## development environment setup (Windows)
this little section will teach you how to get either Visual Studio or MinGW ready for building Furnace.
### MinGW through MSYS2
I recommend you to use this because the compiler produces faster builds and it doesn't use a lot of disk space.
there's some command line-fu in here, so I hope you're prepared.
install it through [MSYS2](https://www.msys2.org/), a Linux-like environment for Windows.
follow the guide up to step 4.
MSYS2 provides a variety of environments, but we'll work with the MINGW64 one. don't "run MSYS2 now". go to the Start menu and launch MSYS2 with the MINGW64 environment (blue icon).
we'll install a couple packages, including GCC, CMake, Git and Ninja.
type the following in the MSYS2 console, and then press Enter.
if you are patient enough, can stand 50GB of stuff and want the Microsoft experience, you may install [Visual Studio](https://visualstudio.microsoft.com) (no, not "Code"... that's just a text editor with IDE features). it is an easy-to-use IDE and compiler that comes in both free and paid versions.
the installer also lets you install Git and CMake. Visual Studio integrates nicely with these.
however I recommend you install Git standalone so you can clone the repo correctly.
## development environment setup (macOS)
install the Xcode command line tools. open a Terminal and type:
if building with the Visual Studio command line tools, make sure you have started the native tools command prompt. [Microsoft has a guide here](https://learn.microsoft.com/en-us/cpp/build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line?view=msvc-170).
if building with MinGW, make sure you have started the MSYS2 MINGW64 environment.
#### CMake or Git
did you install these?
if you installed them through Visual Studio or MinGW, you may have to set the environment as I described above.
### CMake errors
#### No source or binary directory provided
the two dots after the `cmake` command are important. it tells CMake where the CMakeLists.txt file is at (two dots mean "parent directory", which makes sense since we are in the `build` directory inside the Furnace repo).
read the compilation guide again.
#### add\_subdirectory missing
if it says something about a missing directory in `extern`, then either:
if CMake says something about NMake, then it means it couldn't find Visual Studio, or it didn't feel like finding Visual Studio.
try running CMake again but tell it to use the Visual Studio generator (`-G "Visual Studio 17 2022"`). type `cmake --help` for a list of generators.
#### CMake was unable to find a build program
don't run CMake standalone unless you have Visual Studio or a compiler installed.
if you are in the MSYS2 MINGW64 environment, make sure you installed `mingw-w64-x86_64-cmake` instead of `cmake`. restart the environment after doing so.
#### Does not match the generator used previously
yeah I know you probably hit this error right now. delete the build directory (or just CMakeCache.txt and CMakeFiles) and try again.
#### The C compiler is not able to compile a simple test program
something is really wrong, or you are trying to use a compiler outside of an environment.
launch the appropriate environment and try again.
if you are using MSYS2, make sure you have launched the MINGW64 environment. do **not** install `gcc`! instead, install `mingw-w64-x86_64-gcc`.
#### ALSA API requested but no ALSA dev libraries found
install the ALSA development libraries (libasound-dev or something like that).
also make sure you've installed the rest of dependencies so you don't hit one of the errors below...
#### Compatibility with CMake < 3.5 has been removed from CMake
CMake 4.0 has removed support for cmake\_minimum\_required earlier than 3.5. Furnace 0.6.8 has been updated for this, but if you are building an older version, pass `-DCMAKE_POLICY_VERSION_MINIMUM=3.5` to CMake so you can force it to succeed.
### Furnace errors
#### The code execution cannot proceed because libintl-8.dll was not found
this is because sadly libintl (what we use for language support) only exists as a dynamic library (a .dll) on Windows. run CMake again with `-DUSE_MOMO=ON` and then build to fix it.
#### x11 not available/SDL not configured with OpenGL/GLX support
make sure you have installed the Mesa and X11 development libraries. use your package manager to do so.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
