This document (Feb 2022) will take you through the steps needed to build Open Rails from the source code and to run and start debugging it.
To work with the code, you will need an installation of Microsoft Visual Studio and also content that is standalone (doesn't rely on sharing files from 3rd parties).
Visual Studio provides the Git tools to clone the Open Rails repository and submit your changes as a pull request.
Any new features will also require matching changes to the Open Rails Manual, so a Docker container is provided that works with Visual Studio Code to build the manual in either HTML or PDF.
64-bit Windows from version 7 with Service Pack 1 upwards. Open Rails can also be developed on a virtual machine. If you want to use 32-bit Windows, then Visual Studio Code will not be available to you for editing the manual, so please ask for help on the Elvas Tower forum.
Download and install Visual Studio 2019 Community Edition from Microsoft. (Other editions will work but this one is free. Version 2022 will also work, but this is reported as significantly slower. Version 2017 is not recommended as in Feb 2022 we are moving towards .Net 5 which is incompatible.)
The only "workload" needed is .NET desktop development. Some optional tools which may be useful are also checked.
You don't have to create an Microsoft account for 2019, but there is little downside.
You will be prompted to "Get started" and should "Clone a repository" from https://github.com/openrails/openrails.git
On completion, the Solution Explorer view will list the solution ORTS.sln.
Pick it to receive a prompt:
The purpose of the Launcher project is to check whether the user's PC has the software libraries installed to run Open Rails. It uses libraries which are installed on even old PCs, so that it can run on them without error and report any problems.
However the framework needed to build that project is not installed automatically, so choose the option highlighted by the cursor in the image above.
Finally we get to see a list of the projects in the Open Rails solution.
Note: There is no project called OpenRails. Instead, the Launcher project builds an executable called OpenRails.exe.
Use Build > Rebuild Solution to compile and link the source code into executable and DLL files.
Initially, your local repository contrains an empty folder Programs. The executable files just created are saved in this folder.
At this point you can switch to the Windows File Explorer or the command line and run OpenRails.exe. This will carry out some checks and then run Menu.exe.
When debugging, it will be easier to start the program from within Visual Studio. First, set the desired project to be the Startup Project which will run when you press Debug > Start Debugging.
Now pressing F5, Start or Debug > Start Debugging will launch the project Menu.exe in debugging mode.
Without content, all you can run is Menu.exe (or OpenRails.exe which runs Menu.exe) and some of the contributed tools.
The easiest content to install is Demo Model 1. Another recommendation is the test track from Coals To Newcastle as its small size makes it quick to load and it is designed for testing.
Unzip into a new folder.
Using Open Rails Menu.exe and Options > Content > Add, add the folder "Demo Model 1" to the list of installation profiles.
Select Demo model 1 as the Installation profile.
Pressing Start will run the simulation program RunActivity.exe. You can also run this from the command line by providing appropriate arguments. If you hold down the Alt key while pressing the Start button, these arguments are copied into the Windows paste buffer.
From Visual Studio, using Project > Properties > Debug > Command line arguments, these arguments can be pasted into the RunActivity project. If this is the set to be the Startup Project for the solution, pressing F5 will launch RunActivity.exe on the selected activity with debugging in place.
The Open Rails manual is written in ReStructuredText which is processed into a multi-page HTML document or a single-page PDF document.
Note: This section is based on this Pull Request. There are several components to install but, after that, producing a revised manual is just a click away.
This interactive development environment (IDE) is not related to the Visual Studio IDE.
Download from Download Visual Studio Code - Mac, Linux, Windows and run the installer.
Use the icon to add a new extension.
Search for the extension "Remote Containers".
And install it into Visual Studio Code.
Download from https://docs.docker.com/desktop/windows/install/ and run the installer.
Docker provides a closed environment so that our script to build the manual can be run knowing that it will not be broken by any subsequent changes on the PC.
Use the default settings.
Installation takes a few minutes.
You will be prompted to close and restart your PC.
You may receive a prompt to install WSL 2 separately. Click the link to the website.
The link takes you to Step 3 and 4.
Run PowerShell as Administrator.
Enter the command provided.
Return to the webpage for Step 4 and download WSL 2 and install it.
Once this is installed, return to the Docker Desktop prompt and press Restart.
This re-starts Docker Desktop, not your PC.
Now that Docker Desktop is running, start Visual Studio Code.
Note: Before using Visual Studio Code to edit the manual, you should always start Docker Desktop first.
Press F1 to find the command list and search for Remote Containers: Open Folder in Container...
Using Windows File Explorer, search your repository for Source\Documentation\Manual
All the manual files will be listed.
To build the manual, enter a command in the Terminal pane of Visual Studio Code. The default command is make html which builds the file Source\Documentation\Manual\_build\html\index.html
There is a shortcut for this command: Ctrl+Shift+B.
The PDF at Source\Documentation\Manual_build\latex\Manual.pdf can be built with the command: make latexpdf
Open Rails uses Git for source code control. In addition to using Git from the command line, there are many programs that provide a graphical front-end.
Visual Studio 2019 includes facilities for working with Git, see https://docs.microsoft.com/en-gb/visualstudio/version-control/?view=vs-2019
For guidance on contributing, see https://github.com/openrails/openrails/blob/master/Docs/Contributing.md