4ce8f3f935
Currently in the entire C API of WPILib we have ~8 different ways of handling strings. The C API actually isn't built for pure C callers (We don't actually have any of those). Instead, they're built for interop between languages like LabVIEW and C# which can talk to C API's directly. For output parameters, the choice was fairly obvious. An output struct containing a const string pointer and a length makes the most sense. Its easy to use these from most other languages, and doesn't require special null termination handling. Freeing these is also easy, as if you ever receive one of these string structures, theres just a single function call to free it. Input parameters are a bit more complex. To be used from pure C, and from LabVIEW, a null terminated string is the best in most cases. However, null terminated strings in general have a lot of downsides. Additionally, from LabVIEW there are other considerations around encoding that having a wrapper struct helps make a bit easier. From a language like C#, a wrapper struct is by far the easiest, as custom marshalling can make it trivial to marshal both UTF8 and UTF16 strings down. The final consideration is its nice to have an identical concept for both input and output. It makes the rules fairly easy to understand. WPILib will not have any APIs that manipulate a string allocated externally. This means WPI_String can be const, as across the boundary it is always const. If a WPILib API takes a const WPI_String*, WPILib will not manipulate or attempt to free that string, and that string is treated as an input. It is up to the caller to handle that memory, WPILib will never hold onto that memory longer than the call. If a WPILib API takes a WPI_String*, that string is an output. WPILib will allocate that API with WPI_AllocateString(), fill in the string, and return to the caller. When the caller is done with the string, they must free it with WPI_FreeString(). If an output struct contains a WPI_String member, that member is considered read only, and should not be explicitly freed. The caller should call the free function for that struct. If an array of WPI_Strings are returned, each individual string is considered read only, and should not be explicitly freed. The free function for that array should be called by the caller. If an input struct containing a WPI_String, or an input array of WPI_Strings is passed to WPILib, the individual strings will not be manipulated or freed by WPILib, and the caller owns and should free that memory. Callbacks also follow these rules. The most common is a callback either getting passed a const WPI_String* or a struct containing a WPI_String. In both of these cases, the callback target should consider these strings read only, and not attempt to free them or manipulate them.
WPILib Project
Welcome to the WPILib project. This repository contains the HAL, WPILibJ, and WPILibC projects. These are the core libraries for creating robot programs for the roboRIO.
WPILib Mission
The WPILib Mission is to enable FIRST Robotics teams to focus on writing game-specific software rather than focusing on hardware details - "raise the floor, don't lower the ceiling". We work to enable teams with limited programming knowledge and/or mentor experience to be as successful as possible, while not hampering the abilities of teams with more advanced programming capabilities. We support Kit of Parts control system components directly in the library. We also strive to keep parity between major features of each language (Java, C++, Python, and NI's LabVIEW), so that teams aren't at a disadvantage for choosing a specific programming language. WPILib is an open source project, licensed under the BSD 3-clause license. You can find a copy of the license here.
Quick Start
Below is a list of instructions that guide you through cloning, building, publishing and using local allwpilib binaries in a robot project. This quick start is not intended as a replacement for the information further listed in this document.
- Clone the repository with
git clone https://github.com/wpilibsuite/allwpilib.git - Build the repository with
./gradlew buildor./gradlew build --build-cacheif you have an internet connection - Publish the artifacts locally by running
./gradlew publish - Update your
build.gradleto use the artifacts
Building WPILib
Using Gradle makes building WPILib very straightforward. It only has a few dependencies on outside tools, such as the ARM cross compiler for creating roboRIO binaries.
Requirements
- JDK 17
- Note that the JRE is insufficient; the full JDK is required
- On Ubuntu, run
sudo apt install openjdk-17-jdk - On Windows, install the JDK 17 .msi from the link above
- On macOS, install the JDK 17 .pkg from the link above
- C++ compiler
- On Linux, install GCC 11 or greater
- On Windows, install Visual Studio Community 2022 and select the C++ programming language during installation (Gradle can't use the build tools for Visual Studio)
- On macOS, install the Xcode command-line build tools via
xcode-select --install. Xcode 13 or later is required.
- ARM compiler toolchain
- Run
./gradlew installRoboRioToolchainafter cloning this repository - If the WPILib installer was used, this toolchain is already installed
- Run
- Raspberry Pi toolchain (optional)
- Run
./gradlew installArm32Toolchainafter cloning this repository
- Run
On macOS ARM, run softwareupdate --install-rosetta. This is necessary to be able to use the macOS x86 roboRIO toolchain on ARM.
Setup
Clone the WPILib repository and follow the instructions above for installing any required tooling. The build process uses versioning information from git. Downloading the source is not sufficient to run the build.
See the styleguide README for wpiformat setup instructions.
Building
All build steps are executed using the Gradle wrapper, gradlew. Each target that Gradle can build is referred to as a task. The most common Gradle task to use is build. This will build all the outputs created by WPILib. To run, open a console and cd into the cloned WPILib directory. Then:
./gradlew build
To build a specific subproject, such as WPILibC, you must access the subproject and run the build task only on that project. Accessing a subproject in Gradle is quite easy. Simply use :subproject_name:task_name with the Gradle wrapper. For example, building just WPILibC:
./gradlew :wpilibc:build
The gradlew wrapper only exists in the root of the main project, so be sure to run all commands from there. All of the subprojects have build tasks that can be run. Gradle automatically determines and rebuilds dependencies, so if you make a change in the HAL and then run ./gradlew :wpilibc:build, the HAL will be rebuilt, then WPILibC.
There are a few tasks other than build available. To see them, run the meta-task tasks. This will print a list of all available tasks, with a description of each task.
If opening from a fresh clone, generated java dependencies will not exist. Most IDEs will not run the generation tasks, which will cause lots of IDE errors. Manually run ./gradlew compileJava from a terminal to run all the compile tasks, and then refresh your IDE's configuration (In VS Code open settings.gradle and save).
Faster builds
./gradlew build builds everything, which includes debug and release builds for desktop and all installed cross compilers. Many developers don't need or want to build all of this. Therefore, common tasks have shortcuts to only build necessary components for common development and testing tasks.
./gradlew testDesktopCpp and ./gradlew testDesktopJava will build and run the tests for wpilibc and wpilibj respectively. They will only build the minimum components required to run the tests. ./gradlew testDesktop will run both testDesktopJava and testDesktopCpp.
testDesktopCpp, testDesktopJava, and testDesktop tasks also exist for the following projects:
apriltagcameraservercscorehalntcorewpilibNewCommandswpimathwpinetwpiunitswpiutilromiVendordepxrpVendordep
These can be ran with ./gradlew :projectName:task.
./gradlew buildDesktopCpp and ./gradlew buildDesktopJava will compile wpilibcExamples and wpilibjExamples respectively. The results can't be ran, but they can compile.
Build Cache
Run with --build-cache on the command-line to use the shared build cache artifacts generated by the continuous integration server. Example:
./gradlew build --build-cache
Using Development Builds
Please read the documentation available here
Custom toolchain location
If you have installed the FRC Toolchain to a directory other than the default, or if the Toolchain location is not on your System PATH, you can pass the toolChainPath property to specify where it is located. Example:
./gradlew build -PtoolChainPath=some/path/to/frc/toolchain/bin
Formatting/linting
Once a PR has been submitted, formatting can be run in CI by commenting /format on the PR. A new commit will be pushed with the formatting changes.
wpiformat
wpiformat can be executed anywhere in the repository via py -3 -m wpiformat on Windows or python3 -m wpiformat on other platforms.
Java Code Quality Tools
The Java code quality tools Checkstyle, PMD, and Spotless can be run via ./gradlew javaFormat. SpotBugs can be run via the spotbugsMain, spotbugsTest, and spotbugsDev tasks. These tools will all be run automatically by the build task. To disable this behavior, pass the -PskipJavaFormat flag.
If you only want to run the Java autoformatter, run ./gradlew spotlessApply.
CMake
CMake is also supported for building. See README-CMAKE.md.
Running examples in simulation
Examples can be run in simulation with the following command:
./gradlew wpilibcExamples:runExample
./gradlew wpilibjExamples:runExample
where Example is the example's folder name.
Publishing
If you are building to test with other dependencies or just want to export the build as a Maven-style dependency, simply run the publish task. This task will publish all available packages to ~/releases/maven/development. If you need to publish the project to a different repo, you can specify it with -Prepo=repo_name. Valid options are:
- development - The default repo.
- beta - Publishes to ~/releases/maven/beta.
- stable - Publishes to ~/releases/maven/stable.
- release - Publishes to ~/releases/maven/release.
The maven artifacts are described in MavenArtifacts.md
Structure and Organization
The main WPILib code you're probably looking for is in WPILibJ and WPILibC. Those directories are split into shared, sim, and athena. Athena contains the WPILib code meant to run on your roboRIO. Sim is WPILib code meant to run on your computer, and shared is code shared between the two. Shared code must be platform-independent, since it will be compiled with both the ARM cross-compiler and whatever desktop compiler you are using (g++, msvc, etc...).
The integration test directories for C++ and Java contain test code that runs on our test-system. When you submit code for review, it is tested by those programs. If you add new functionality you should make sure to write tests for it so we don't break it in the future.
The hal directory contains more C++ code meant to run on the roboRIO. HAL is an acronym for "Hardware Abstraction Layer", and it interfaces with the NI Libraries. The NI Libraries contain the low-level code for controlling devices on your robot. The NI Libraries are found in the ni-libraries project.
The upstream_utils directory contains scripts for updating copies of thirdparty code in the repository.
The styleguide repository contains our style guides for C++ and Java code. Anything submitted to the WPILib project needs to follow the code style guides outlined in there. For details about the style, please see the contributors document here.