You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This document will take you through the steps needed to build Open Rails from the source code and to run and start debugging it.
4
-
5
-
Line ending in two spaces.
6
-
7
-
dummy line
8
-
9
-
Line ending in br.<br/>
10
-
11
-
dummy line
12
-
13
-
Line ending in pspace/p.<p> </p>
14
-
15
-
dummy line
16
-
17
-
Line ending in p/p.<p></p>
18
-
19
-
dummy line
20
-
3
+
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.
21
4
22
5
## Overview
23
6
@@ -29,30 +12,30 @@ Any new features will also require matching changes to the Open Rails Manual, so
29
12
30
13
## Windows
31
14
32
-
Use any Windows from version 7 with Service Pack 1 upwards. Open Rails can also be developed on a virtual machine.
15
+
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]([http://www.elvastower.com/forums/).
Download and install Visual Studio 2019 Community Edition from Microsoft.
39
-
(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.)
22
+
(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.)<p> </p>
@@ -73,7 +56,7 @@ On completion, the Solution Explorer view will list the solution ORTS.sln. Pick
73
56
74
57
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.
75
58
76
-
However the framework needed to build that project is not installed automatically, so choose the option highlighted in the image above.
59
+
However the framework needed to build that project is not installed automatically, so choose the option highlighted in the image above. <p> </p>
77
60
78
61
79
62
@@ -85,7 +68,7 @@ Note: There is no project called OpenRails. Instead, the Launcher project builds
85
68
86
69
87
70
88
-
Use Build > Rebuild Solution to compile and link the source code into executable and DLL files.
71
+
Use *Build > Rebuild Solution* to compile and link the source code into executable and DLL files.
89
72
90
73
91
74
@@ -95,47 +78,150 @@ Initially, your local repository contrains an empty folder Programs. The executa
95
78
96
79
97
80
98
-
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.
81
+
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.<p> </p>
99
82
100
83
101
84
102
-
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.
85
+
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*.<p> </p>
103
86
104
87
105
88
106
-
Now pressing F5, Start or Debug > Start Debugging will launch the project Menu.exe in debugging mode.
89
+
Now pressing F5, Start or *Debug > Start Debugging* will launch the project Menu.exe in debugging mode.
107
90
108
91
## Content
109
92
110
-
Without content, all you can run is Menu.exe (or OpenRails.exe which runs Menu.exe) and some of the contributed tools.
93
+
Without content, all you can run is Menu.exe (or OpenRails.exe which runs Menu.exe) and some of the contributed tools.<p> </p>
111
94
112
95
113
96
114
97
The easiest content to install is [Demo Model 1](http://openrails.org/download/content/).
115
-
Another recommendation is the [test track from Coals To Newcastle](9https://www.coalstonewcastle.com.au/physics/route/) as its small size makes it quick to load and it is designed for testing.
98
+
Another recommendation is the [test track from Coals To Newcastle](9https://www.coalstonewcastle.com.au/physics/route/) as its small size makes it quick to load and it is designed for testing.<p> </p>
116
99
117
100
118
101
119
-
Unzip into a new folder.
102
+
Unzip into a new folder.<p> </p>
120
103
121
104
122
105
123
-
Start Open Rails Menu.exe, and use Options > Content > Add to add the folder "Demo Model 1" to the list of installation profiles.
106
+
Start Open Rails Menu.exe, and use *Options > Content > Add* to add the folder "Demo Model 1" to the list of installation profiles.<p> </p>
124
107
125
108
126
109
127
110
Select Demo model 1 as the Installation profile.
128
111
129
112
130
113
131
-
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.
114
+
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.<p> </p>
132
115
133
116
134
117
135
-
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.
118
+
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.<p> </p>
136
119
137
120
138
121
139
122
## Installing Tools for Open Rails Manual
140
123
141
-
## Submitting Changes
124
+
Note: This section is based on this [Pull Request](https://github.com/openrails/openrails/pull/557)
125
+
There are several components to install but after that producing a revised manual is just a click away.
126
+
127
+
### Install Visual Studio Code
128
+
129
+
This interactive development environment (IDE) is unrelated to the Visual Studio IDE. The Open Rails manual is written in [ReStructuredText](https://docutils.sourceforge.io/rst.html) which is processed into a [multi-page HTML document](https://open-rails.readthedocs.io/en/latest/) or a [single-page PDF document](http://openrails.org/files/OpenRails-Testing-Manual.pdfvmw).
130
+
131
+
### Download and install Visual Code
132
+
133
+
Download from [Download Visual Studio Code - Mac, Linux, Windows](https://code.visualstudio.com/download) and run the installer.
134
+
135
+
### Add Extension - Remote Containers
136
+
137
+
138
+
139
+
Use the icon to add a new extension.
140
+
141
+
142
+
143
+
Search for the extension "Remote Containers".
144
+
145
+
146
+
147
+
And install it into Visual Studio Code.
148
+
149
+
### Download and install Docker Desktop
150
+
151
+
152
+
153
+
Download from [https://docs.docker.com/desktop/windows/install/](https://docs.docker.com/desktop/windows/install/) and run the installer.
154
+
155
+
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.
156
+
157
+
158
+
159
+
Use the default settings.
160
+
161
+
162
+
163
+
Installation takes a few minutes.
164
+
165
+
You will be prompted to close and restart your PC.
166
+
167
+
168
+
169
+
You may receive a prompt to install WSL 2 separately. Click the link.
170
+
171
+
172
+
173
+
The link takes you to Step 3 and 4.
174
+
175
+
176
+
177
+
Run PowerShell as Administrator.
178
+
179
+
180
+
181
+
Enter the command provided.
182
+
183
+
184
+
185
+
Return to the webpage for Step 4 and download WSL 2 and install it.
186
+
187
+
188
+
189
+
Once this is installed, return to the Docker Desktop prompt and press Restart.
190
+
191
+
192
+
193
+
This re-starts Docker Desktop, not your PC.
194
+
195
+
Now that Docker Desktop is running, start Visual Studio Code.
196
+
197
+
198
+
199
+
Press F1 to find the command list and search for Remote Containers: Open Folder in Container...
200
+
201
+
202
+
203
+
Using Windows File Explorer, search your repository for Source\Documentation\Manual
204
+
205
+
206
+
207
+
All the manual files will be listed.
208
+
209
+
210
+
211
+
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
212
+
213
+
214
+
215
+
There is a shortcut for this command: Ctrl+Shift+B.
216
+
217
+
218
+
219
+
The PDF at Source\Documentation\Manual\_build\latex\Manual.pdf can be built with the command: _make latexpdf_
220
+
221
+
## Git and Contributing to Open Rails
222
+
223
+
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.
224
+
225
+
Visual Studio 2019 includes facilities for working with Git, see [https://docs.microsoft.com/en-gb/visualstudio/version-control/?view=vs-2019](https://docs.microsoft.com/en-gb/visualstudio/version-control/?view=vs-2019)
226
+
227
+
For guidance on contributing, see [https://github.com/openrails/openrails/blob/master/Docs/Contributing.md](https://github.com/openrails/openrails/blob/master/Docs/Contributing.md)
0 commit comments