Installation

Note

BunyipsFTC users (members of the MBHS Student Robotics Club), BunyipsLib is already installed into the BunyipsFTC repo. All you need to do is create a new Gradle configuration for your robot by following the steps here. Other repositories should follow the installation instructions.

BunyipsLib is distributed via a git submodule. This allows for direct source code modification by you, as BunyipsLib should work harmoniously with your codebase.

To get BunyipsLib in your codebase, you'll need experience with git, the Gradle build system, and the command line (used in this tutorial). The recommended FTC SDK version is specified with one of the badges at the top of the README. The specified version is the one that BunyipsLib is tested with and will have the most compatibility. Generally, this is the latest version of the SDK as offered by FTC.

Integrating BunyipsLib into your codebase

1. Getting the code
   From the top-level directory in your own FtcRobotController fork, run git submodule add https://github.com/Murray-Bridge-Bunyips/BunyipsLib, which should clone and create a new BunyipsLib folder with the source code.
   
   
2. Adding dependencies
   BunyipsLib depends on RoadRunner, FtcDashboard, and Kotlin (plus Apache Commons Math). These tools make development faster and are legal FTC tools.
   You will first need to install Kotlin v1.9.20, alongside Dokka which is used for generating documentation. To do this, go to your copy of the FtcRobotController project, and open the top-level build.gradle file. Copy in the lines that are modified in the snippet below between the buildscript braces. Append these properties to their appropriate area.

buildscript {
   ext.kotlin_version = '1.9.20'

   dependencies {
       classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
       classpath "org.jetbrains.dokka:dokka-gradle-plugin:$kotlin_version"
   }
}

Your top-level build.gradle should look something like this.

After you've done this, go to your build.dependencies.gradle file located in your top-level directory and paste the following dependencies in the dependencies {} block:

implementation "com.acmerobotics.roadrunner:ftc:0.1.14"
implementation "com.acmerobotics.roadrunner:core:1.0.0"
implementation "com.acmerobotics.roadrunner:actions:1.0.0"
implementation "com.acmerobotics.dashboard:dashboard:0.4.16"
implementation 'org.apache.commons:commons-math3:3.6.1'

Finally, add this to the top repositories {} block in the same file:

maven { url = 'https://maven.brott.dev/' }

Your dependencies file should look something like this. Note for BunyipsLib <5.0.0 - ≥5.1.0 that PhotonFTC is a dependency, so this can be omitted if you don't wish to use it. (Photon is now optionally defined at your user-level OpModes, due to volatility)

5. Telling Gradle BunyipsLib exists
   First, we need tell Gradle to build BunyipsLib as well. To do this, open settings.gradle in your top-level directory and append the following lines.

include ':BunyipsLib'

Finally, we need to tell Gradle that we want to integrate BunyipsLib with the TeamCode module. Open the build.gradle file associated with the TeamCode module, and append to the dependencies {} block:

implementation project(':BunyipsLib')

5. Gradle sync
   In Android Studio, run a Gradle Sync (Ctrl+Shift+O) to ensure your classpaths are updated with BunyipsLib and your dependencies are downloaded.
   
   
6. You're done!
   You now have access to BunyipsLib. Ensure to read how to update BunyipsLib and how to ensure your future cloners can get BunyipsLib in their local repositories.

Using the BunyipsLib submodule in a clone of your fork

For new cloners of your fork with BunyipsLib, you can simply run git clone --recurse-submodules <YOUR_REPO>.

For repositories that already exist, run git submodule update --init --recursive, to fetch the submodule that was placed in your .gitmodules top-level directory file.

Updating BunyipsLib

BunyipsLib is continually getting updates to ensure the latest features have been rigorously debugged and tested. To ensure that you aren't using code that I've accidentally implemented a 30-gigabyte memory leak into (it has happened before), you'll need to know how to update it.

Navigate to the directory of your BunyipsLib submodule, and run git pull on the master branch for the latest dev changes. This should bring any changes into your repository. If you wish to use a more stable version of BunyipsLib, you can switch to the SemVer tags that are available in the repository using git checkout <tag> and available in the Releases section. These versions are more stable and are less likely to have runtime errors or bugs, with changes fully documented.

What's next?

Once you've installed BunyipsLib, start looking at the various paradigms related to using BunyipsLib, as well as how to configure your robot.