From bd0977accee5955150f65520fb33e95511a9714c Mon Sep 17 00:00:00 2001 From: Mahi Date: Tue, 25 Nov 2025 15:42:30 +0600 Subject: [PATCH] Update README with usage instructions and example --- README.md | 160 ++++++++++++++++++++++-------------------------------- 1 file changed, 65 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index 84ae747..98178fe 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,72 @@ -# swift-benchmark - -A Swift library for benchmarking code snippets, similar to -[google/benchmark](https://github.com/google/benchmark). - -Example: - +# Swift Benchmark +Swift Benchmark is a library for writing and running benchmarks in Swift. +## Getting Started +To use `swift-benchmark` in your project, add it to your `Package.swift` dependencies: +```swift +// swift-tools-version:5.3 +import PackageDescription +let package = Package( +name: "YourProject", +dependencies: [ +.package(url: "https://github.com/google/swift-benchmark.git", from: "0.1.0"), +], +targets: [ +.target( +name: "YourProject", +dependencies: ["Benchmark"]), +] +) +``` +Then build your project: +```bash +swift build +``` +## Example Benchmark ```swift import Benchmark - -benchmark("add string reserved capacity") { - var x: String = "" - x.reserveCapacity(2000) - for _ in 1...1000 { - x += "hi" - } +let benchmark = BenchmarkSuite(name: "Sample") { suite in +suite.benchmark("Loop") { +for _ in 0..<1_000_000 { } +} } - -Benchmark.main() +Benchmark.main([benchmark]) ``` - -At runtime, you can filter which benchmarks to run by using the `--filter` command line flag. For -more details on what options are available, pass either the `-h` or `--help` command line flags. - -Example: - -```terminal -$ swift run -c release BenchmarkMinimalExample --help -USAGE: benchmark-command [--allow-debug-build] [--filter ] [--filter-not ] [--iterations ] [--warmup-iterations ] [--min-time ] [--max-iterations ] [--time-unit ] [--inverse-time-unit ] [--columns ] [--format ] [--quiet] - -OPTIONS: - --allow-debug-build Overrides check to verify optimized build. - --filter Run only benchmarks whose names match the regular expression. - --filter-not - Exclude benchmarks whose names match the regular expression. - --iterations - Number of iterations to run. - --warmup-iterations - Number of warm-up iterations to run. - --min-time Minimal time to run when automatically detecting number iterations. - --max-iterations - Maximum number of iterations to run when automatically detecting number iterations. - --time-unit Time unit used to report the timing results. - --inverse-time-unit - Inverse time unit used to report throughput results. - --columns Comma-separated list of column names to show. - --format Output format (valid values are: json, csv, console, none). - --quiet Only print final benchmark results. - -h, --help Show help information. - -$ swift run -c release BenchmarkMinimalExample -running add string no capacity... done! (1832.52 ms) -running add string reserved capacity... done! (1813.96 ms) - -name time std iterations ------------------------------------------------------------ -add string no capacity 37435 ns ± 6.22 % 37196 -add string reserved capacity 37022 ns ± 1.75 % 37749 +## Running Benchmarks +Use Swift Package Manager: +```bash +swift run BenchmarkMinimalExample ``` - -For more examples, see -[Sources/BenchmarkMinimalExample](./Sources/BenchmarkMinimalExample) and -[Sources/BenchmarkSuiteExample](./Sources/BenchmarkSuiteExample). - -## Usage - -Add this library as a SwiftPM dependency: - -```swift -let package = Package( - name: ... , - products: [ - .executable(name: "Benchmarks", targets: ["Benchmarks"]) - ], - dependencies: [ - .package(url: "https://github.com/google/swift-benchmark", from: "0.1.0") - ], - targets: [ - .target( - name: "Benchmarks", - dependencies: [.product(name: "Benchmark", package: "swift-benchmark")] - ) - ] -) +Example output: ``` - -## Roadmap - -The project is in an early stage and offers only a basic set of benchmarking -utilities. Feel free to file issues and feature requests to help us prioritize -what to do next. - -## License - -Please see [LICENSE](LICENSE) for details. - +name time std iterations +------------------------------------------------ +Loop 12.3 ms ±0.2 ms 100 +``` +## Writing Good Benchmarks +- Keep your benchmark small and focused +- Avoid doing I/O inside benchmark loops +- Prefer micro-benchmarks to isolate performance of small code blocks +- Benchmark consistent workloads ## Contributing - -Please see [CONTRIBUTING.md] for details. - -[CONTRIBUTING.md]: CONTRIBUTING.md - +We welcome contributions! If you want to improve this README or add new +benchmarks: +1. Fork the repository +2. Create a new branch: +```bash +git checkout -b improve-readme +``` +3. Make your changes +4. Stage your changes: +```bash +git add README.md +``` +5. Commit your changes: +```bash +git commit -m "Improve README with usage and example" +``` +6. Push your branch: +```bash +git push origin improve-readme +``` +7. Open a Pull Request to the main repository with a clear description +8. Don't forget to sign the Google CLA \ No newline at end of file