Skip to content

Commit 9df4754

Browse files
AhmedAredahAhmedAredah
committed
Add comprehensive build instructions to HOW_TO_BUILD.md
1 parent e92c238 commit 9df4754

1 file changed

Lines changed: 368 additions & 0 deletions

File tree

‎HOW_TO_BUILD.md‎

Lines changed: 368 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,368 @@
1+
# How to Build ShipNetSim
2+
3+
This document provides comprehensive instructions for building ShipNetSim from source code. ShipNetSim is a Qt6-based maritime simulation software with modular components including GUI, server, and core simulation engine.
4+
5+
## Table of Contents
6+
7+
- [Prerequisites](#prerequisites)
8+
- [Dependencies](#dependencies)
9+
- [Build Configuration Options](#build-configuration-options)
10+
- [Platform-Specific Instructions](#platform-specific-instructions)
11+
- [Building the Project](#building-the-project)
12+
- [Installation](#installation)
13+
- [Troubleshooting](#troubleshooting)
14+
15+
## Prerequisites
16+
17+
### Required Software
18+
19+
- **CMake**: Version 3.24 or higher
20+
- **C++ Compiler**:
21+
- Windows: MSVC 2019/2022 (Visual Studio Build Tools)
22+
- Linux: GCC or Clang with C++23 support
23+
- macOS: Xcode with C++23 support
24+
- **Qt6**: Version 6.4.2 or higher
25+
- **Git**: For cloning the repository
26+
27+
### System Requirements
28+
29+
- **RAM**: Minimum 8GB, recommended 16GB+
30+
- **Storage**: At least 10GB free space for build artifacts
31+
- **Graphics**: OpenGL-compatible graphics card (for GUI components)
32+
33+
## Dependencies
34+
35+
ShipNetSim requires several third-party libraries. The build system expects these to be installed in standard locations or specified via CMake variables.
36+
37+
### Core Dependencies (Required for All Builds)
38+
39+
1. **Qt6 Components**:
40+
- Qt6::Core
41+
- Qt6::Concurrent
42+
- Qt6::Xml
43+
- Qt6::Sql
44+
- Qt6::Network
45+
46+
2. **GDAL** (Geospatial Data Abstraction Library)
47+
- Windows: Download from [OSGeo4W](https://trac.osgeo.org/osgeo4w/) or [GISInternals](https://www.gisinternals.com/)
48+
- Linux: `sudo apt-get install libgdal-dev` (Ubuntu/Debian) or `yum install gdal-devel` (CentOS/RHEL)
49+
- macOS: `brew install gdal`
50+
51+
3. **GeographicLib**
52+
- Windows: Download from [GeographicLib website](https://geographiclib.sourceforge.io/)
53+
- Linux: `sudo apt-get install libgeographiclib-dev`
54+
- macOS: `brew install geographiclib`
55+
56+
### GUI-Specific Dependencies (Required if BUILD_GUI=ON)
57+
58+
4. **OpenSceneGraph (OSG)**
59+
- Windows: Download precompiled binaries or build from source
60+
- Linux: `sudo apt-get install libopenscenegraph-dev`
61+
- macOS: `brew install open-scene-graph`
62+
63+
5. **osgEarth**
64+
- Download from [osgEarth website](http://osgearth.org/)
65+
- Must be compatible with your OpenSceneGraph version
66+
67+
6. **osgQt (osgQOpenGL)**
68+
- Often bundled with osgEarth or available separately
69+
70+
7. **KDReports**
71+
- Download from [KDAB website](https://www.kdab.com/development-resources/qt-tools/kd-reports/)
72+
73+
8. **Additional Qt6 Components**:
74+
- Qt6::Widgets
75+
- Qt6::OpenGLWidgets
76+
- Qt6::PrintSupport
77+
78+
### Server-Specific Dependencies (Required if BUILD_SERVER=ON)
79+
80+
9. **Container Library**
81+
- Custom library (path must be specified via CONTAINER_SEARCH_PATHS)
82+
83+
10. **RabbitMQ-C**
84+
- Windows: Download from [RabbitMQ-C releases](https://github.com/alanxz/rabbitmq-c/releases)
85+
- Linux: `sudo apt-get install librabbitmq-dev`
86+
- macOS: `brew install rabbitmq-c`
87+
88+
### Optional Dependencies
89+
90+
11. **Fontconfig** (Linux/macOS only)
91+
- Linux: Usually pre-installed, or `sudo apt-get install libfontconfig1-dev`
92+
- macOS: `brew install fontconfig`
93+
94+
## Build Configuration Options
95+
96+
ShipNetSim provides several CMake options to customize the build:
97+
98+
### Primary Build Options
99+
100+
| Option | Default | Description |
101+
|--------|---------|-------------|
102+
| `BUILD_GUI` | `ON` | Build the GUI components (ShipNetSimGUI) |
103+
| `BUILD_SERVER` | `ON` | Build the server components (ShipNetSimServer) |
104+
| `BUILD_INSTALLER` | `ON` | Build the installer package |
105+
106+
### Path Configuration Options
107+
108+
| Variable | Default (Windows) | Description |
109+
|----------|-------------------|-------------|
110+
| `QT_BIN_DIR` | `C:/Qt/6.4.2/msvc2019_64/bin` | Path to Qt binary directory |
111+
| `osgEarth_DIR` | `C:/Program Files/OSGEarth/cmake` | Path to osgEarth CMake directory |
112+
| `OpenSceneGraph_DIR` | `C:/Program Files/OpenSceneGraph` | Path to OpenSceneGraph directory |
113+
| `OSGQT_INCLUDE_DIR` | `C:/Program Files/osgQt/include` | Path to osgQt include directory |
114+
| `OSGQOPENGL_LIB` | `C:/Program Files/osgQt/lib/osg145-osgQOpenGL.lib` | Path to osgQt library |
115+
| `KDREPORTS_DIR` | `C:/KDAB/KDReports-2.3.95/lib/cmake/KDReports-qt6` | Path to KDReports CMake directory |
116+
| `CONTAINER_SEARCH_PATHS` | Platform-specific | Path to Container library |
117+
| `RABBITMQ_CMAKE_DIR` | Platform-specific | Path to RabbitMQ-C CMake directory |
118+
| `GDAL_ROOT_HINTS` | Empty | Hint path for GDAL installation |
119+
| `GeographicLib_ROOT_HINTS` | Empty | Hint path for GeographicLib installation |
120+
121+
### Compiler Options
122+
123+
The build system automatically configures compiler-specific options:
124+
125+
- **MSVC**: `/W4`, `/MP`, optimization flags (`/Od /Zi` for Debug, `/O2` for Release)
126+
- **GCC/Clang**: `-Wall`, optimization flags (`-O0 -g` for Debug, `-O3` for Release)
127+
128+
## Platform-Specific Instructions
129+
130+
### Windows
131+
132+
1. **Install Visual Studio Build Tools**:
133+
```cmd
134+
# Download Visual Studio Installer and install:
135+
# - MSVC v143 compiler toolset
136+
# - Windows 10/11 SDK
137+
# - CMake tools for Visual Studio
138+
```
139+
140+
2. **Install Qt6**:
141+
```cmd
142+
# Download Qt Online Installer
143+
# Install Qt 6.4.2 or later with MSVC 2019/2022 kit
144+
```
145+
146+
3. **Set Environment Variables** (Optional):
147+
```cmd
148+
set Qt6_DIR=C:\Qt\6.4.2\msvc2019_64\lib\cmake\Qt6
149+
set PATH=%PATH%;C:\Qt\6.4.2\msvc2019_64\bin
150+
```
151+
152+
### Linux (Ubuntu/Debian)
153+
154+
1. **Install Build Tools**:
155+
```bash
156+
sudo apt-get update
157+
sudo apt-get install build-essential cmake git
158+
```
159+
160+
2. **Install Qt6**:
161+
```bash
162+
sudo apt-get install qt6-base-dev qt6-tools-dev qt6-tools-dev-tools
163+
sudo apt-get install libqt6opengl6-dev libqt6openglwidgets6
164+
```
165+
166+
3. **Install Dependencies**:
167+
```bash
168+
sudo apt-get install libgdal-dev libgeographiclib-dev
169+
sudo apt-get install libopenscenegraph-dev libfontconfig1-dev
170+
sudo apt-get install librabbitmq-dev
171+
```
172+
173+
### macOS
174+
175+
1. **Install Xcode Command Line Tools**:
176+
```bash
177+
xcode-select --install
178+
```
179+
180+
2. **Install Homebrew** (if not already installed):
181+
```bash
182+
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
183+
```
184+
185+
3. **Install Dependencies**:
186+
```bash
187+
brew install cmake qt6 gdal geographiclib
188+
brew install open-scene-graph fontconfig rabbitmq-c
189+
```
190+
191+
## Building the Project
192+
193+
### 1. Clone the Repository
194+
195+
```bash
196+
git clone https://github.com/VTTI-CSM/ShipNetSim.git
197+
cd ShipNetSim
198+
```
199+
200+
### 2. Create Build Directory
201+
202+
```bash
203+
mkdir build
204+
cd build
205+
```
206+
207+
### 3. Configure with CMake
208+
209+
#### Basic Configuration (All Components)
210+
211+
```bash
212+
cmake .. -DCMAKE_BUILD_TYPE=Release
213+
```
214+
215+
#### Custom Configuration Examples
216+
217+
**GUI Only Build**:
218+
```bash
219+
cmake .. \
220+
-DCMAKE_BUILD_TYPE=Release \
221+
-DBUILD_GUI=ON \
222+
-DBUILD_SERVER=OFF \
223+
-DBUILD_INSTALLER=OFF
224+
```
225+
226+
**Server Only Build**:
227+
```bash
228+
cmake .. \
229+
-DCMAKE_BUILD_TYPE=Release \
230+
-DBUILD_GUI=OFF \
231+
-DBUILD_SERVER=ON \
232+
-DBUILD_INSTALLER=OFF
233+
```
234+
235+
**Custom Paths (Windows Example)**:
236+
```bash
237+
cmake .. \
238+
-DCMAKE_BUILD_TYPE=Release \
239+
-DQT_BIN_DIR="C:/Qt/6.5.0/msvc2022_64/bin" \
240+
-DosgEarth_DIR="C:/OSGEarth/cmake" \
241+
-DOpenSceneGraph_DIR="C:/OpenSceneGraph" \
242+
-DGDAL_ROOT_HINTS="C:/OSGeo4W64"
243+
```
244+
245+
### 4. Build the Project
246+
247+
```bash
248+
# Build all targets
249+
cmake --build . --config Release
250+
251+
# Or build specific targets
252+
cmake --build . --target ShipNetSimCore --config Release
253+
cmake --build . --target ShipNetSimGUI --config Release
254+
cmake --build . --target ShipNetSimServer --config Release
255+
```
256+
257+
#### Parallel Building
258+
259+
```bash
260+
# Use multiple cores (replace 8 with your core count)
261+
cmake --build . --config Release --parallel 8
262+
```
263+
264+
### 5. Build Installer (Optional)
265+
266+
```bash
267+
cmake --build . --target ShipNetSimInstaller --config Release
268+
```
269+
270+
## Installation
271+
272+
### Install to System
273+
274+
```bash
275+
# Configure with install prefix
276+
cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local
277+
278+
# Build and install
279+
cmake --build . --config Release
280+
cmake --install . --config Release
281+
```
282+
283+
### Package Creation
284+
285+
```bash
286+
# Create installer package (Windows)
287+
cmake --build . --target package --config Release
288+
289+
# This creates a .exe installer in the build directory
290+
```
291+
292+
## Troubleshooting
293+
294+
### Common Issues
295+
296+
1. **Qt6 Not Found**:
297+
```bash
298+
# Set Qt6_DIR explicitly
299+
cmake .. -DQt6_DIR="C:/Qt/6.4.2/msvc2019_64/lib/cmake/Qt6"
300+
```
301+
302+
2. **GDAL Not Found**:
303+
```bash
304+
# Specify GDAL path
305+
cmake .. -DGDAL_ROOT_HINTS="C:/OSGeo4W64"
306+
```
307+
308+
3. **OpenSceneGraph Issues**:
309+
```bash
310+
# Ensure all OSG components are found
311+
cmake .. -DOpenSceneGraph_DIR="C:/OpenSceneGraph"
312+
```
313+
314+
4. **Missing DLLs (Windows)**:
315+
- Ensure all dependency DLLs are in PATH or copied to output directory
316+
- The installer automatically handles DLL deployment
317+
318+
5. **Permission Issues**:
319+
- Run CMake and build commands with appropriate permissions
320+
- On Windows, consider running as Administrator for system-wide installs
321+
322+
### Build Output Structure
323+
324+
After successful build, the output structure will be:
325+
```
326+
build/
327+
├── bin/ # Executables and DLLs
328+
│ ├── ShipNetSim.exe # Core executable
329+
│ ├── ShipNetSimGUI.exe # GUI application (if BUILD_GUI=ON)
330+
│ ├── ShipNetSimServer.exe # Server application (if BUILD_SERVER=ON)
331+
│ └── ShipNetSimCore.dll # Core library
332+
├── lib/ # Static libraries
333+
├── data/ # Application data files
334+
└── plugins/ # Qt plugins (Windows)
335+
```
336+
337+
### Environment Variables
338+
339+
For development, you may want to set:
340+
341+
```bash
342+
# Windows
343+
set PATH=%PATH%;C:\Qt\6.4.2\msvc2019_64\bin
344+
set QT_PLUGIN_PATH=C:\Qt\6.4.2\msvc2019_64\plugins
345+
346+
# Linux/macOS
347+
export PATH=$PATH:/path/to/qt6/bin
348+
export QT_PLUGIN_PATH=/path/to/qt6/plugins
349+
```
350+
351+
### Getting Help
352+
353+
If you encounter build issues:
354+
355+
1. Check the [GitHub Issues](https://github.com/VTTI-CSM/ShipNetSim/issues) page
356+
2. Verify all dependencies are correctly installed
357+
3. Ensure CMake version compatibility (3.24+)
358+
4. Contact the maintainers: [AhmedAredah@vt.edu](mailto:AhmedAredah@vt.edu)
359+
360+
### Contributing
361+
362+
Before submitting pull requests:
363+
364+
1. Ensure your changes build successfully on your target platform
365+
2. Follow the project's coding standards
366+
3. Update documentation as needed
367+
368+
For detailed contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).

0 commit comments

Comments
 (0)