|
| 1 | +# Contributing to scala-polars |
| 2 | + |
| 3 | +Thanks for your interest in contributing to `scala-polars`! 🚀 |
| 4 | + |
| 5 | +Whether you're fixing a bug, writing tests/ documentation, or building features, we welcome your help. |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +## 🛠️ Project Structure |
| 10 | + |
| 11 | +- `core/`: The main Scala and Java API used by end users |
| 12 | +- `native/`: A Rust module compiled into a shared library via Cargo and linked via JNI |
| 13 | +- `examples/`: Sample applications in both Scala and Java |
| 14 | + |
| 15 | +--- |
| 16 | + |
| 17 | +## 💧 Build Prerequisites |
| 18 | + |
| 19 | +Ensure the following are installed: |
| 20 | + |
| 21 | +- Java 8+ (JDK) |
| 22 | +- [Rust](https://www.rust-lang.org/tools/install) |
| 23 | +- [sbt](https://www.scala-sbt.org/) |
| 24 | + |
| 25 | +--- |
| 26 | + |
| 27 | +## Compilation Process |
| 28 | + |
| 29 | +`sbt` is the primary build tool for this project, and all the required interlinking has been done in such a way that |
| 30 | +your |
| 31 | +IntelliJ IDE or an external build works in the same way. This means that whether you are in development mode or want to |
| 32 | +build to distribute, the process of the build remains the same and is more or less abstracted. |
| 33 | + |
| 34 | +The build process that sbt triggers involves the following steps |
| 35 | + |
| 36 | +- Compile the rust code present in the `native` module to a binary. |
| 37 | +- Compile the scala and java (if any) facade code. |
| 38 | +- Copy the built rust binary to the classpath of scala code during its build at a fixed location. |
| 39 | + |
| 40 | +All the above steps happen automatically when you run an sbt build job that triggers `compile` phase. Other than |
| 41 | +this, during the package phase, the scala, java code and the built rust binary are added to the built jar(s). To keep |
| 42 | +everything monolithic, the `native` module is not packaged as a jar, only `core` module is. |
| 43 | + |
| 44 | +The above process might look complicated, and it actually is 😂, but since all the internally sbt wiring is already in |
| 45 | +place, the user facing process is fairly straight-forward. This can be done by going through the following steps in |
| 46 | +sequence firstly ensure JDK 8+, sbt and the latest rust |
| 47 | +compiler are installed, then follow the commands below as per the need. |
| 48 | + |
| 49 | +--- |
| 50 | + |
| 51 | +## 🏗 Build Commands |
| 52 | + |
| 53 | +### Full project (Rust + Scala/Java) |
| 54 | + |
| 55 | +```bash |
| 56 | +sbt compile |
| 57 | +``` |
| 58 | + |
| 59 | +### Native Rust library only |
| 60 | + |
| 61 | +```bash |
| 62 | +sbt generateNativeLibrary |
| 63 | +``` |
| 64 | + |
| 65 | +### Locally publish |
| 66 | + |
| 67 | +```bash |
| 68 | +sbt publishLocal |
| 69 | +``` |
| 70 | + |
| 71 | +### Fat JAR |
| 72 | + |
| 73 | +```bash |
| 74 | +sbt assembly |
| 75 | +``` |
| 76 | + |
| 77 | +--- |
| 78 | + |
| 79 | +## 🔍 Testing |
| 80 | + |
| 81 | +Run unit tests via: |
| 82 | + |
| 83 | +```bash |
| 84 | +sbt test |
| 85 | +``` |
| 86 | + |
| 87 | +--- |
| 88 | + |
| 89 | +## ✍️ Conventions |
| 90 | + |
| 91 | +- Follow idiomatic Scala where possible. |
| 92 | +- Keep Rust and Scala types in sync when modifying the native interface. |
| 93 | +- Test across multiple Scala versions (`2.12`, `2.13`, `3.x`) if making public API changes. |
| 94 | +- Document any native API changes clearly. |
| 95 | + |
| 96 | +--- |
| 97 | + |
| 98 | +## 📤 Publishing Snapshots |
| 99 | + |
| 100 | +If you're a maintainer: |
| 101 | + |
| 102 | +```bash |
| 103 | +# Publish to Sonatype snapshots |
| 104 | +sbt +publish |
| 105 | +``` |
| 106 | + |
| 107 | +--- |
| 108 | + |
| 109 | +## 📬 Getting Help |
| 110 | + |
| 111 | +- [Open an issue](https://github.com/chitralverma/scala-polars/issues) |
| 112 | +- Join the [Polars Discord](https://discord.gg/4UfP5cfBE7) |
| 113 | + |
| 114 | +We appreciate every contribution ❤️ |
| 115 | + |
0 commit comments