blob: 8b1411ef0449ac4e39c4887a7e4803d920f98b46 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
# DS-Sim
DS-Sim is a open-source simulator for distributed systems, written in Java. It provides a powerful environment for simulating and learning about distributed systems concepts.
## Features
- Protocol simulation
- Event handling
- Lamport and Vector time implementations
- Modern Java-based architecture
- Interactive GUI using Swing
- Comprehensive logging
## Requirements
- Java 21 or higher
- Maven 3.8 or higher
## Quick Start
```bash
# Clone the repository
git clone https://github.com/yourusername/ds-sim.git
cd ds-sim
# Set JAVA_HOME if needed (Fedora Linux)
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk
# Build and run in one step
mvn clean package && java -jar target/ds-sim-*.jar
```
## Building the Project
### Full Build
```bash
# Clean and build everything (recommended)
mvn clean package
```
### Development Build
```bash
# Fast compilation only
mvn compile
# Build without running tests (faster)
mvn package -DskipTests
```
## Testing
The project includes comprehensive unit tests and a testing framework for protocol simulations.
### Running Unit Tests
```bash
# Run all unit tests (CI-compatible)
mvn test
# Run specific test class
mvn test -Dtest=VSMessageTest
# Run tests matching a pattern
mvn test -Dtest="*Protocol*"
# Build without tests
mvn clean package -DskipTests
```
### Test Coverage
- **Core components**: VSTask, VSMessage, process management
- **Event system**: Event handling and registration
- **Protocol implementations**: PingPong, Two-Phase Commit, Berkeley Time, etc.
- **Total**: 141 unit tests (headless-compatible)
### Protocol Simulation Testing
DS-Sim includes a framework for testing protocol simulations:
```bash
# Interactive test runner (Note: produces GUI errors in headless mode)
./scripts/test-protocols.sh
```
For detailed testing information, see [docs/testing-guide.md](docs/testing-guide.md).
### View Test Results
```bash
# Test reports are generated in:
target/surefire-reports/
# View summary of last test run
cat target/surefire-reports/*.txt
```
### Build Output
After building, you'll find:
- `target/ds-sim-1.0.1.jar` - Executable JAR with all dependencies
- `target/classes/` - Compiled class files
- `target/original-ds-sim-1.0.1.jar` - JAR without dependencies
## Running the Application
### Method 1: Using JAR File (Recommended)
```bash
# After building, run the executable JAR
java -jar target/ds-sim-*.jar
```
## Cleaning the Project
### Remove All Build Artifacts
```bash
# Clean everything Maven generated
mvn clean
```
### Force Clean (if needed)
```bash
# Remove target directory manually if Maven clean fails
rm -rf target/
mvn clean
```
## Development Workflow
```bash
# 1. Make code changes
# 2. Quick compile to check for errors
mvn compile
# 3. Run tests
mvn test
# 4. Build and test the application
mvn package && java -jar target/ds-sim-1.0.1.jar
# 5. Clean up when done
mvn clean
```
## Maven Command Reference
| Command | Purpose | When to Use |
|---------|---------|-------------|
| `mvn compile` | Compile source code only | Quick syntax checking |
| `mvn test` | Run unit tests | Before committing code |
| `mvn package` | Create JAR files | Ready to distribute |
| `mvn clean package` | Full clean build | First build or after major changes |
| `mvn exec:java` | Run application directly | Quick testing without JAR |
| `mvn javadoc:javadoc` | Generate documentation | Creating API docs |
| `mvn clean` | Remove build artifacts | Clean workspace |
| `mvn package -DskipTests` | Fast build without tests | Development iterations |
## Project Structure
```
ds-sim/
├── src/
│ └── main/
│ ├── java/ # Source code
│ │ ├── core/ # Process and message handling
│ │ ├── events/ # Event system
│ │ ├── protocols/ # Distributed algorithms
│ │ ├── simulator/ # Main simulation engine
│ │ └── utils/ # Utilities and helpers
│ └── resources/ # Configuration files
├── docs/ # Documentation
│ ├── index.md # Documentation index
│ ├── architecture.md # System architecture and design
│ ├── developer-guide.md # Guide for extending DS-Sim
│ └── testing-guide.md # Comprehensive testing guide
├── saved-simulations/ # Example simulation files
├── scripts/ # Development scripts
└── pom.xml # Maven configuration
```
## Documentation
📚 **[Full Documentation Index](docs/index.md)** - Complete list of all documentation
### Key Documents:
- **[Architecture Guide](docs/architecture.md)** - System design, components, and diagrams
- **[Developer Guide](docs/developer-guide.md)** - How to create new protocols and events
- **[Testing Guide](docs/testing-guide.md)** - Comprehensive testing documentation
- **[Timestamp Events Guide](docs/timestamp-events-guide.md)** - Using timestamp-triggered events
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the terms of the license included in the repository.
## Acknowledgments
- Original VS-Sim project: https://codeberg.org/snonux/vs-sim/
|
