diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e752645e105..96bcc80cf93 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,7 @@ So you want to contribute your changes back to WPILib. Great! We have a few cont - [General Contribution Rules](#general-contribution-rules) - [What to Contribute](#what-to-contribute) +- [Design Philosophy](#design-philosophy) - [Contribution Process](#contribution-process) - [Coding Guidelines](#coding-guidelines) - [Submitting Changes](#submitting-changes) @@ -13,12 +14,11 @@ So you want to contribute your changes back to WPILib. Great! We have a few cont ## General Contribution Rules -- Everything in the library must work for the 4000+ teams that will be using it. +- Everything in the library must work for the 14000+ teams that will be using it. - We need to be able to maintain submitted changes, even if you are no longer working on the project. - Tool suite changes must be generally useful to a broad range of teams - Excluding bug fixes, changes in one language generally need to have corresponding changes in other languages. - Some features, such the addition of C++23 for WPILibC or Functional Interfaces for WPILibJ, are specific to that version of WPILib only. New language features added to C++ must be wrappable in Python for [RobotPy](https://github.com/robotpy). - - Substantial changes often need to have corresponding LabVIEW changes. To do this, we will work with NI on these large changes. - Changes should have tests. - Code should be well documented. - This involves writing tutorials and/or usage guides for your submitted feature. These articles are then hosted on the [WPILib](https://docs.wpilib.org/) documentation website. See the [frc-docs repository](https://github.com/wpilibsuite/frc-docs) for more information. @@ -28,14 +28,27 @@ So you want to contribute your changes back to WPILib. Great! We have a few cont - Bug reports and fixes - We will generally accept bug fixes without too much question. If they are only implemented for one language, we will implement them for any other necessary languages. Bug reports are also welcome, please submit them to our GitHub issue tracker. - While we do welcome improvements to the API, there are a few important rules to consider: - - Features must be added to Java (WPILibJ), C++ (WPILibC), with rare exceptions. - - Most of Python (RobotPy) is created by wrapping WPILibC with pybind11 via robotpy-build. However, new features to the command framework should also be submitted to [robotpy-commands-v2](https://github.com/robotpy/robotpy-commands-v2) as the command framework is reimplemented in Python. - - During competition season, we will not merge any new feature additions. We want to ensure that the API is stable during the season to help minimize issues for teams. + - Features must be added to Java (WPILibJ), C++ (WPILibC), and Python with rare exceptions. + - Most of Python (RobotPy) is created by wrapping WPILibC with pybind11 via semiwrap. In general, new user-facing functions or classes should have the proper wrapper configs updated, typically located in a YAML file with the same name as the header. See the [in-repo RobotPy README](./README-RobotPy.md) for more info and how to partially auto-update the configs. However, the command framework is reimplemented in Python, and requires code to be ported instead of being wrapped via semiwrap. + - During competition season, we will not merge any new feature additions or removals. We want to ensure that the API is stable during the season to help minimize issues for teams. - Ask about large changes before spending a bunch of time on them! See [Contribution Process](#contribution-process) for where to ask. - Features that make it easier for teams with less experience to be more successful are more likely to be accepted. - Features in WPILib should be broadly applicable to all teams. Anything that is team specific should not be submitted. - As a rule, we are happy with the general structure of WPILib. We are not interested in major rewrites of all of WPILib. We are open to talking about ideas, but backwards compatibility is very important for WPILib, so be sure to keep this in mind when proposing major changes. - - Generally speaking, we do not accept code for specific sensors. We have to be able to test the sensor in hardware on the WPILib test bed. Additionally, hardware availability for teams is important. Therefore, as a general rule, the library only directly supports hardware that is in the Kit of Parts. If you are a company interested in getting a sensor into the Kit of Parts, please contact FIRST directly at frcparts@firstinspires.org. + - While the library may contain support for specific sensors, these are typically items contained in the FIRST Robotics Competition Kit of Parts or commonly used hardware identified by FIRST or core WPILib Developers. If you think a certain sensor should be supported in WPILib, you may submit an issue justifying the reasons why it should be supported and approval will be determined by FIRST or core WPILib Developers. If you are a company interested in getting a sensor into the Kit of Parts, please contact FIRST directly at frcparts@firstinspires.org. + +## Design Philosophy + +WPILib's general design philosophy strays far away from the traditional Object-Oriented Programming architectures dominant in enterprise codebases. The general points to follow for WPILib are as follows: + +- Prefer functions and composition over inheritance. Inheritance is rigid and often prevents evolution, as adding or removing methods from an inherited class risks breakage. For similar reasons, functional interfaces (`std::function` in C++) are preferred over actual interfaces. +- Avoid opaque black-boxes of functionality. Classes like RamseteCommand or HolonomicDriveController (both removed in 2027) are good examples of this. While they look like a good abstraction that helps beginners, the black-box nature means they are [difficult to debug](https://github.com/wpilibsuite/allwpilib/issues/3350) and it's impossible to instrument the internals to figure out what's going on, or they are extremely clunky to use compared to composing the individual component (thus defeating the point of abstracting it away; SwerveControllerCommand construction was [a huge pile of opaque arguments glued together](https://github.com/wpilibsuite/allwpilib/blob/v2026.2.2/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/swervecontrollercommand/RobotContainer.java#L104-L114)). Composition is strongly preferred, with strong documentation and examples describing how to do that composition. +- Error at compile time, not runtime. Despite our best efforts, there will always be people who don't read stack traces (understandable for beginner programmers). Compile time errors show up in builds and in an IDE, which is much easier and faster for people to pinpoint and debug. Use language features to make invalid code impossible to build. + - The Matrix class in Java is an example of this. While clunky due to Java's weak generics system, it enforces correct Matrix dimensions at compile time, with the MatBuilder factory method throwing if the array passed in is the wrong size, which leads to the next point: +- Try to only throw exceptions at code startup, and only for things that are obviously incorrect. Robots shouldn't quit, and it's a real "feels bad" moment when yours does, especially in a match. It's oftentimes better to have a robot continue running when it sees nonsensical state as opposed to outright crashing, since other components are often still functional. If you can't make invalid code a compile time error, throwing at the start of the robot program is the next best solution, but avoid throwing in functions likely to be called throughout a robot's runtime. + - Sometimes the behavior of functions are just incorrect if invalid data is passed in, and throwing is one of the only options. This is a judgement call, but if there are no other options, throwing can be okay. + - An alternative to throwing is logging an error, typically with [the Alerts framework](https://docs.wpilib.org/en/latest/docs/software/telemetry/persistent-alerts.html); this is a good choice for runtime errors. Also see https://github.com/wpilibsuite/allwpilib/issues/6766 for an example of not throwing exceptions, but simply logging an error on invalid data. + - Note that hardware configuration issues such as a sensor not existing isn't necessarily obviously incorrect; it could be that the wrong port was specified, but it could also be unplugged due to external factors. Throwing just because it's unplugged can make for a "feels bad" moment, and should be avoided. ## Contribution Process diff --git a/DevelopmentBuilds.md b/DevelopmentBuilds.md index 4241a8e5640..08cf9e8d7c7 100644 --- a/DevelopmentBuilds.md +++ b/DevelopmentBuilds.md @@ -13,7 +13,7 @@ This article contains instructions on building projects using a development buil Development builds are the per-commit build hosted every time a commit is pushed to the [allwpilib](https://github.com/wpilibsuite/allwpilib/) repository. These builds are then hosted on [artifactory](https://frcmaven.wpi.edu/artifactory/webapp/#/home). -To build a project using a development build, find the build.gradle file and open it. Then, add the following code below the plugin section and replace YEAR with the year of the development version. It is also necessary to use a 2027 GradleRIO version, ie `2027.0.0-alpha-3` +To build a project using a development build, find the build.gradle file and open it. Then, add the following code below the plugin section and replace YEAR with the year of the development version. It is also necessary to use a 2027 GradleRIO version, ie `2027.0.0-alpha-5` ```groovy wpi.maven.useLocal = false @@ -27,7 +27,7 @@ Java ```groovy plugins { id "java" - id "edu.wpi.first.GradleRIO" version "2027.0.0-alpha-3" + id "org.wpilib.GradleRIO" version "2027.0.0-alpha-5" } wpi.maven.useLocal = false @@ -40,7 +40,7 @@ C++ plugins { id "cpp" id "google-test-test-suite" - id "edu.wpi.first.GradleRIO" version "2027.0.0-alpha-3" + id "org.wpilib.GradleRIO" version "2027.0.0-alpha-5" } wpi.maven.useLocal = false @@ -61,7 +61,7 @@ Java ```groovy plugins { id "java" - id "edu.wpi.first.GradleRIO" version "2027.0.0-alpha-3" + id "org.wpilib.GradleRIO" version "2027.0.0-alpha-5" } wpi.maven.useLocal = false @@ -74,7 +74,7 @@ C++ plugins { id "cpp" id "google-test-test-suite" - id "edu.wpi.first.GradleRIO" version "2027.0.0-alpha-3" + id "org.wpilib.GradleRIO" version "2027.0.0-alpha-5" } wpi.maven.useLocal = false diff --git a/GeneratedFiles.md b/GeneratedFiles.md index 4a2b78861d3..0e390044cfb 100644 --- a/GeneratedFiles.md +++ b/GeneratedFiles.md @@ -23,3 +23,6 @@ To maintain consistency with other Python scripts, copy an existing `generate_*. ### (Re)Generating files and committing them Once your Python script is complete, you can run `python generate_.py` to generate the files. Once you're finished with your files, commit these files to Git. If you regenerated the files and Git indicates the files have changed, but the diff doesn't show any changes, only the line endings have changed. If you expected changes to the generated code, you didn't correctly make changes. If you didn't expect changes, you can ignore this and discard the changes. Also ensure that you've marked the Python script as executable, since this is necessary for CI workflows to run your scripts. To add your script to the CI workflows, edit [.github/workflows/pregen_all.py](.github/workflows/pregen_all.py), and add your script alongside the rest of the scripts. + +#### (Re)Generating QuickBuffers files +Regenerating QuickBuffers files requires the Protocol Buffers compiler (protoc), and the QuickBuffers plugin, which can be found on [their releases page](https://github.com/HebiRobotics/QuickBuffers/releases). Once you have both, you can pass their paths into the generation scripts with `--protoc` and `--quickbuf_plugin` and regenerate the files. diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 045aa6d282d..0407f6dc08b 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -1,23 +1,20 @@ ## Publishing Third Party Dependencies -Currently the 3rd party deps are imgui, opencv, google test, libssh, and apriltaglib +Currently the 3rd party external deps are opencv, libssh, ceres, and gtsam. For publishing these dependencies, the version needs to be manually updated in the publish.gradle file of their respective repository. -Then, in the azure build for the dependency you want to build for, manually start a pipeline build (As of current, this is the `Run Pipeline` button). -A variable needs to be added called `RUN_AZURE_ARTIFACTORY_RELEASE`, with a value of `true`. Then when the pipeline gets started, the final build outputs will be updated to artifactory. +Then, upload a new tag for the dependency you want to build for, which will automatically start a build. +The CI workflow should set `RUN_AZURE_ARTIFACTORY_RELEASE` to `true` on tagged runs. Then when the pipeline gets started, the final build outputs will be uploaded to artifactory. To use newer versions of C++ dependencies, in `shared/config.gradle`, update the version related to the specific dependency. For Java dependencies, there is likely a file related to the specific dependency in the shared folder. Update the version in there. -Note, changing artifact locations (This includes changing the artifact year currently, I have an issue open to change this) requires updating the `native-utils` plugin +Note, changing artifact locations requires updating the `native-utils` plugin; specifically, the `configureDependencies` method in the `WPINativeUtilsExtension` class. ## Publishing allwpilib allwpilib publishes to the development repo on every push to main. To publish a release build, upload a new tag, and a release will automatically be built and published. -## Publishing desktop tools -Desktop tools publish to the development repo on every push to main. To publish a release build, upload a new tag, and a release will automatically be built and published. - ## Publishing VS Code -Before publishing, make sure to update the gradlerio version in `vscode-wpilib/resources/gradle/version.txt` Also make sure the gradle wrapper version matches the wrapper required by gradlerio. +Before publishing, make sure to update the GradleRIO version in `vscode-wpilib/resources/gradle/version.txt`. Also make sure the Gradle Wrapper version matches the wrapper required by GradleRIO. Upon pushing a tag, a release will be built, and the files will be uploaded to the releases on GitHub. ## Publishing GradleRIO diff --git a/MavenArtifacts.md b/MavenArtifacts.md index 80704b0334e..8f1ede093d0 100644 --- a/MavenArtifacts.md +++ b/MavenArtifacts.md @@ -21,7 +21,7 @@ Example: org.wpilib.wpilibj:wpilibj-java:version ``` -The second types are native artifacts. These are usually published as `zip` files. The `-sources` and `-headers` classifiers contain the sources and headers respectively for the library. Each artifact also contains a classifier for each platform we publish. This platform is in the format `{os}{arch}`. The full list of supported platforms can be found in [native-utils](https://github.com/wpilibsuite/native-utils/blob/main/src/main/java/edu/wpi/first/nativeutils/WPINativeUtilsExtension.java#L94). If the library is built statically, it will have `static` appended to the classifier. Additionally, if the library was built in debug mode, `debug` will be appended to the classifier. The platform artifact only contains the binaries for a specific platform. Note that the binary artifacts never contain the headers, you always need the `-headers` classifier to get those. +The second types are native artifacts. These are usually published as `zip` files. The `-sources` and `-headers` classifiers contain the sources and headers respectively for the library. Each artifact also contains a classifier for each platform we publish. This platform is in the format `{os}{arch}`. The full list of supported platforms can be found in [native-utils in the Platforms nested class](https://github.com/wpilibsuite/native-utils/blob/main/src/main/java/org/wpilib/nativeutils/WPINativeUtilsExtension.java). If the library is built statically, it will have `static` appended to the classifier. Additionally, if the library was built in debug mode, `debug` will be appended to the classifier. The platform artifact only contains the binaries for a specific platform. Note that the binary artifacts never contain the headers, you always need the `-headers` classifier to get those. If the library is Java and C++ and has a JNI component, the native artifact will have a shared library containing JNI entrypoints alongside the C++ shared library. This JNI shared library will have a `jni` suffix in the file name. @@ -38,7 +38,7 @@ This repository provides the following artifacts. Below each artifact is its dep For C++, if building with static dependencies, the listed order should be the link order in your linker. -All artifacts are based at `org.wpilib.halsim.artifactname` in the repository. +All artifacts are based at `org.wpilib.artifactname` in the repository. * wpiutil @@ -52,32 +52,33 @@ All artifacts are based at `org.wpilib.halsim.artifactname` in the repository. * wpiutil * ntcore - * wpiutil * wpinet + * wpiutil * glass/libglass - * wpiutil - * wpimath * wpigui + * wpimath + * wpiutil * glass/libglassnt - * wpiutil - * wpinet + * wpigui * ntcore + * wpinet * wpimath - * wpigui + * wpiutil * hal + * ntcore * wpiutil * halsim - * wpiutil - * wpinet + * libglassnt + * libglass * ntcore * wpimath * wpigui - * libglass - * libglassnt + * wpinet + * wpiutil * cscore * opencv @@ -126,12 +127,16 @@ All artifacts are based at `org.wpilib.halsim.artifactname` in the repository. ### Third Party Artifacts -This repository provides the builds of the following third party software. - -All artifacts are based at `org.wpilib.thirdparty.frcYEAR` in the repository. +This repository provides the builds of the following third party software: -* apriltaglib * googletest * imgui -* opencv -* libssh + +Other software can be found in their corresponding GitHub repositories: + +* ceres: https://github.com/wpilibsuite/thirdparty-ceres +* gtsam: https://github.com/wpilibsuite/thirdparty-gtsam +* opencv: https://github.com/wpilibsuite/thirdparty-opencv +* libssh: https://github.com/wpilibsuite/thirdparty-libssh + +All artifacts are based at `org.wpilib.thirdparty` in the repository. diff --git a/README-Bazel.md b/README-Bazel.md index a6ce60e7d50..93c9f273fe2 100644 --- a/README-Bazel.md +++ b/README-Bazel.md @@ -1,10 +1,10 @@ # WPILib Bazel Support -WPILib is normally built with Gradle, but [Bazel](https://www.bazel.build/) can also be used to increase development speed due to the superior caching ability and the ability to use remote caching and remote execution (on select platforms) +WPILib is normally built with Gradle, but [Bazel](https://www.bazel.build/) can also be used to increase development speed due to the superior caching ability and the ability to use remote caching and remote execution (on select platforms). ## Prerequisites -- Install [Bazelisk](https://github.com/bazelbuild/bazelisk/releases) and add it to your path. Bazelisk is a wrapper that will download the correct version of bazel specified in the repository. Note: You can alias/rename the binary to `bazel` if you want to keep the familiar `bazel build` vs `bazelisk build` syntax. +- Install [Bazelisk](https://github.com/bazelbuild/bazelisk/releases) and add it to your path. Bazelisk is a wrapper that will download the correct version of Bazel specified in the repository. Note: You can alias/rename the binary to `bazel` if you want to keep the familiar `bazel build` vs `bazelisk build` syntax. ## Building To build the entire repository, simply run `bazel build //...`. To run all of the unit tests, run `bazel test //...` @@ -14,7 +14,7 @@ Other examples: - `bazel coverage //wpiutil/...` - (*Nix only) - Runs a code coverage report for both C++ and Java on all the targets under wpiutil ## User settings -When invoking bazel, it will check if `user.bazelrc` exists for additional, user specified flags. You can use these settings to do things like always ignore buildin a specific folder, or limiting the CPU/RAM usage during a build. +When invoking Bazel, it will check if `user.bazelrc` exists for additional, user specified flags. You can use these settings to do things like always ignore builds in a specific folder, or limiting the CPU/RAM usage during a build. Examples: - `build --build_tag_filters=-wpi-example` - Do not build any targets tagged with `wpi-example` (Currently all of the targets in wpilibcExamples and wpilibjExamples contain this tag) - `build -c opt` - Always build optimized targets. The default compiler flags were chosen to build as fast as possible, and thus don't contain many optimizations @@ -36,12 +36,12 @@ Modify this to your likings if you want to build less. ## Pregenerating Files allwpilib uses extensive use of pre-generating files that are later used to build C++ / Java libraries that are tracked by version control. Quite often, -these pre-generation scripts use some configuration file to create multipile files inside of an output directory. While this process could be accomplished +these pre-generation scripts use some configuration file to create multiple files inside of an output directory. While this process could be accomplished with a `genrule` that would require an explicit listing of every output file, which would be tedious to maintain as well as potentially confusing to people -adding new features those libraries. Therefor, we use `@aspect_bazel_lib` and their `write_source_files` feature to generate these directories. In the event that the generation process creates more than a small handful of predictable files, a custom rule is written to generate the directory. +adding new features those libraries. Therefore, we use `@aspect_bazel_lib` and their `write_source_files` feature to generate these directories. In the event that the generation process creates more than a small handful of predictable files, a custom rule is written to generate the directory. ## Remote Caching -One of the huge benefits of bazel is its remote caching ability. However, due to bazels strict build definitions it is hard to share remote cache artifacts between different computers unless our toolchains are fully hermetic, which means you are unlikely to be able to reuse the cache artifacts published from the `main` branch on your local machine like you might be able to with the `gradle` or `cmake` caches. Luckily the github actions CI machines are generally stable between runs and can reuse cache artifacts, and your local machine should remain stable, so if you set up a free buildbuddy account you can have your forks CI actions be able to use a personalized cache, as well as your local machine. +One of the huge benefits of Bazel is its remote caching ability. However, due to Bazel's strict build definitions, it is hard to share remote cache artifacts between different computers unless our toolchains are fully hermetic, which means you are unlikely to be able to reuse the cache artifacts published from the `main` branch on your local machine like you might be able to with the `gradle` or `cmake` caches. Luckily, the GitHub Actions CI machines are generally stable between runs and can reuse cache artifacts, and your local machine should remain stable, so if you set up a free buildbuddy account you can have your fork's CI actions be able to use a personalized cache, as well as your local machine. For the main `allwpilib` upstream, the cache is only updated on the main branch; pull requests from forks will not be able to modify the cache. However, you can set up your fork to enable its own cache by following the steps below. diff --git a/README-CMake.md b/README-CMake.md index 63e6de66e6a..19b54878aa0 100644 --- a/README-CMake.md +++ b/README-CMake.md @@ -5,16 +5,17 @@ WPILib is normally built with Gradle, however for some systems, such as Linux ba ## Libraries that get built * apriltag * cameraserver +* commandsv2 * commandsv3 * cscore +* datalog * fields * hal (simulation HAL only) * ntcore * romiVendordep * simulation extensions * wpigui -* wpilib (wpilibc, wpilibj, and myRobot) -* commandsv2 +* wpilib (wpilibc, wpilibj, and developerRobot) * wpimath * wpinet * wpiunits @@ -26,9 +27,10 @@ WPILib is normally built with Gradle, however for some systems, such as Linux ba * glass * outlineviewer * sysid +* wpical * halsim_gui (if simulation extensions are enabled) -By default, all libraries get built with a default CMake setup. The libraries are built as shared libraries, and include the JNI libraries as well as building the Java JARs. Data Log Tool and the roboRIO Team Number Setter are only built if libssh is available. +By default, all libraries get built with a default CMake setup. The libraries are built as shared libraries, and include the JNI libraries as well as building the Java JARs. Data Log Tool is only built if libssh is available. ## Prerequisites @@ -36,8 +38,6 @@ OpenCV needs to be findable by CMake. On systems like the Jetson, this is instal If you want JNI and Java, you will need a JDK of at least version 25 installed. In addition, you need a `JAVA_HOME` environment variable set properly and set to the JDK directory. -If you are building with unit tests or simulation modules, you will also need an Internet connection for the initial setup process, as CMake will clone google-test and imgui from GitHub. - ## Build Options The following build options are available: @@ -61,7 +61,7 @@ The following build options are available: * `WITH_TESTS` (ON Default) * This option will build C++ unit tests. These can be run via `ctest -C `, where `` is the build configuration, e.g. `Debug` or `Release`. * `WITH_WPILIB` (ON Default) - * This option will build the HAL and wpilibc/j during the build. The HAL is the simulation HAL, unless the external HAL options are used. The CMake build has no capability to build for the roboRIO. + * This option will build the HAL and wpilibc/j during the build. The HAL is the simulation HAL, unless the external HAL options are used. The CMake build has no capability to build for Systemcore. * `WITH_WPIMATH` (ON Default) * This option will build the wpimath library. This option must be on to build wpilib. * `WITH_WPIUNITS` (`WITH_JAVA` Default) @@ -89,11 +89,11 @@ If you want, you can also use `ccmake` in order to visually set these properties ## Presets -The WPILib CMake setup has a variety of presets for common configurations and options used. The default sets the generator to Ninja and build directory to `build-cmake`. The other presets are `with-java` (sets `WITH_JAVA=ON`), `sccache` (sets the C/C++ compiler launcher to sccache), and `with-java-sccache` (a comibination of `with-java` and `sccache`. +The WPILib CMake setup has a variety of presets for common configurations and options used. The default sets the generator to Ninja and build directory to `build-cmake`. The other presets are `with-java` (sets `WITH_JAVA=ON`), `sccache` (sets the C/C++ compiler launcher to sccache), and `with-java-sccache` (a combination of `with-java` and `sccache`). ## Building -Once you have CMake setup. run `cmake --build .` from the directory you configured CMake in. This will build all libraries possible. We recommend running `cmake --build .` with multiple jobs. For allwpilib, a good rule of thumb is one worker for every 2 GB of available RAM. To run a multiple job build, run the following command with x being the number of jobs you want. +Once you have CMake setup. run `cmake --build .` from the directory you configured CMake in. This will build all libraries possible. We recommend running `cmake --build .` with multiple jobs. For allwpilib, a good rule of thumb is one worker for every 2 GB of available RAM. To run a multi-job build, run the following command with x being the number of jobs you want. ``` cmake --build . --parallel x @@ -211,10 +211,11 @@ If you are missing Java, you will get a message like the following. ``` CMake Error at /usr/share/cmake-3.5/Modules/FindPackageHandleStandardArgs.cmake:148 (message): Could NOT find Java (missing: Java_JAVA_EXECUTABLE Java_JAR_EXECUTABLE - Java_JAVAC_EXECUTABLE Java_JAVAH_EXECUTABLE Java_JAVADOC_EXECUTABLE) + Java_JAVAC_EXECUTABLE Java_JAVAH_EXECUTABLE Java_JAVADOC_EXECUTABLE + Development) ``` -If this happens, make sure you have a JDK of at least version 8 installed, and that your JAVA_HOME variable is set properly to point to the JDK. +If this happens, make sure you have a JDK of at least version 25 installed, and that your JAVA_HOME variable is set properly to point to the JDK. In addition, if you do not need Java, you can disable it with `-DWITH_JAVA=OFF`. @@ -224,7 +225,7 @@ If one of the libraries can't be found, you will get an error similar to this on ``` java.io.IOException: wpiHaljni could not be loaded from path or an embedded resource. - attempted to load for platform /windows/x86-64/ + attempted to load for platform windows-x86_64 Last Load Error: C:\Program Files (x86)\allwpilib\bin\wpiHaljni.dll: Can't find dependent libraries ``` diff --git a/README-RobotPy.md b/README-RobotPy.md index 0136dbb21ca..65ab8eae3f4 100644 --- a/README-RobotPy.md +++ b/README-RobotPy.md @@ -1,23 +1,22 @@ -# robotpy in allwpilb -allwpilib hosts a mirror of RobotPy that can be built with bazel on Linux. The intent of the mirror is to have breaking changes identified early and fixed by the PR creator so that when wpilib releases are made there is much less work required to release a RobotPy version that wraps it. It is not a goal for allwpilib to replace the RobotPy repo; it will still be considered the "source of truth" for python builds and will be responsible for building against all of the applicable architectures and multiple versions of python. +# robotpy in allwpilib +allwpilib hosts a mirror of RobotPy that can be built with Bazel on Linux. The intent of the mirror is to have breaking changes identified early and fixed by the PR creator so that when WPILib releases are made, there is much less work required to release a RobotPy version that wraps it. It is not a goal for allwpilib to replace the RobotPy repo; it will still be considered the "source of truth" for Python builds and will be responsible for building against all of the applicable architectures and multiple versions of Python. ## Build Process -The upstream RobotPy repository uses toml configuration files and semiwrap to produce Meson build scripts. The allwpilib fork uses these toml configuration files to auto generate bazel build scripts. In general, each project (wpiutil, wpimath, etc) defines two pybind extensions; one that simply wraps the native library, and another that adds extension(s) that and contains all of the python files for the library. Both of these subprojects have auto-generated build files; a `robotpy_native_build_info.bzl` for the lidar wraper and `robotpy_pybind_build_info.bzl` which defines the extensions and python library. +The upstream RobotPy repository uses TOML configuration files and semiwrap to produce Meson build scripts. The allwpilib fork uses these TOML configuration files to auto-generate Bazel build scripts. In general, each project (wpiutil, wpimath, etc) defines two pybind extensions; one that simply wraps the native library, and another that adds extension(s) that and contains all of the Python files for the library. Both of these subprojects have auto-generated build files; a `robotpy_native_build_info.bzl` for the native wrapper and `robotpy_pybind_build_info.bzl` which defines the extensions and Python library. -## Disabling robotpy builds -Building the robotpy software on top of the standard C++/Java software can result in more than doubling the amount of time it takes to compile. To skip building the robotpy tooling you can add `--config=skip_robotpy` to the command line or to your `user.bazelrc` +## Disabling RobotPy builds +Building the RobotPy software on top of the standard C++/Java software can result in more than doubling the amount of time it takes to compile. To skip building the RobotPy tooling, you can add `--config=skip_robotpy` to the command line or to your `user.bazelrc`. -# Syncing with robotpy -[Copybara](https://github.com/google/copybara) is used to maintin synchronization between the upstream robotpy repositories and the allwpilib mirror. Github actions can be manually run which will create pull requests that will update all of the robotpy files between the two repositories. The ideal process is that the allwpilib mirror is always building in CI, and once a release is created the RobotPy team can run the `wpilib -> robotpy` copybara task, make any fine tuned adjustements and create their release. In the event that additional changes are made on the robotpy side, they can run the `robotpy -> wpilib` task to push the updates back to the mirror. However the goal of the mirroring the software here is to be able to more rapidly test changes and will hopefully overwhelmingly eliminate the need for syncs this direction. +# Syncing with RobotPy +[Copybara](https://github.com/google/copybara) is used to maintain synchronization between the upstream RobotPy repositories and the allwpilib mirror. GitHub Actions can be manually run, which will create pull requests that will update all of the RobotPy files between the two repositories. The ideal process is that the allwpilib mirror is always building in CI, and once a release is created, the RobotPy team can run the `wpilib -> robotpy` Copybara task, make any fine tuned adjustments and create their release. In the event that additional changes are made on the RobotPy side, they can run the `robotpy -> wpilib` task to push the updates back to the mirror. However, the goal of the mirroring the software here is to be able to more rapidly test changes and will hopefully overwhelmingly eliminate the need for syncs in this direction. ## Creating a user config -The copybara scripts needs to know information about what repositories it will be pushing the sync'd changes. These can be specified on the command line, or you can create a `shared/bazel/copybara/.copybara.json` config file to save your personalized settings to avoid having to type things out every time. To run the full suite of migrations, you need a fork of [allwpilib](https://github.com/wpilibsuite/allwpilib), a fork of [mostrobotpy](https://github.com/robotpy/mostrobotpy), and a fork of robotpy's [commands-v2](https://github.com/robotpy/robotpy-commands-v2). If you only wish to run a subset of commands (i.e. not sync the commands project), you do not need to include that in your user config. +The Copybara scripts needs to know information about what repositories it will be pushing the synced changes to. These can be specified on the command line, or you can create a `shared/bazel/copybara/.copybara.json` config file to save your personalized settings to avoid having to type things out every time. To run the full suite of migrations, you need a fork of [allwpilib](https://github.com/wpilibsuite/allwpilib), a fork of [mostrobotpy](https://github.com/robotpy/mostrobotpy), and a fork of RobotPy's [commands-v2](https://github.com/robotpy/robotpy-commands-v2). If you only wish to run a subset of commands (i.e. not sync the commands project), you do not need to include that in your user config. Example config: -``` +```json { "mostrobotpy_local_repo_path": "/home//git/robotpy/robotpy_monorepo/mostrobotpy", - "mostrobotpy_fork_repo": "https://github.com//mostrobotpy.git", "allwpilib_fork_repo": "https://github.com//allwpilib.git", "robotpy_commandsv2_fork_repo": "https://github.com//robotpy-commands-v2.git" @@ -40,18 +39,17 @@ Example config: - **Pushing changes to mostrobotpy**: - This process is slightly more complicated, because you will almost certainly also need to update the maven artifacts that mostrobopy is using. Because of this, you must also specify the version number that has been published to wpilibs maven repository. If you are trying to get an early, non-released development build pushed over, you can also add the `--development_build` flag + This process is slightly more complicated, because you will almost certainly also need to update the Maven artifacts that mostrobopy is using. Because of this, you must also specify the version number that has been published to WPILib's Maven repository. If you are trying to get an early, non-released development build pushed over, you can also add the `--development_build` flag: `python3 shared/bazel/copybara/run_copybara.py allwpilib_to_mostrobotpy --wpilib_bin_version=2027.0.0-alpha-3-86-g418b381 --development_build -y` - # Debugging Build Errors -The build process is highly automated and automatically parses C++ header files to generate pybind11 bindings. Some of these steps here are considered "pregeneration" steps, and the bazel build system will update build files as necessary. If a new header is added, or if the contents of a header file has changed, some of the pregeneration scripts might need to be run. If you encounter an error building `robotpy` code, it is recommended that you go through these steps to make sure everything is set up correctly. The examples are for `wpilibc`, but similar build tasks and tests exist for each wrapped project +The build process is highly automated and automatically parses C++ header files to generate pybind11 bindings. Some of these steps here are considered "pregeneration" steps, and the Bazel build system will update build files as necessary. If a new header is added, or if the contents of a header file has changed, some of the pregeneration scripts might need to be run. If you encounter an error building `robotpy` code, it is recommended that you go through these steps to make sure everything is set up correctly. The examples are for `wpilibc`, but similar build tasks and tests exist for each wrapped project. ## 1. scan-headers This can be the first source of problems if a new header file has been added. `semiwrap` will look through all of the headers for a library and notify you if a file is not covered by the projects `pyproject.toml` file. Bazel has a test case to ensure the files are up to date. -An example test failure when a new header being introduced. You can run the test with the following command +An example test failure when a new header being introduced. You can run the test with the following command: bazel run //wpilibc:robotpy-wpilib-scan-headers @@ -68,22 +66,22 @@ ExpansionHubServo = "wpi/ExpansionHubServo.hpp" To fix this, you can copy the lines from the console, and add them to the pyproject.toml file, located here `wpilibc/src/main/python/pyproject.toml` ## 2. update-yaml -This process parses all of the header files, and creates a representation of the classes / enums / etc in yaml. Occasionally some functions might be ignored or need custom pybind code, which can be added to these files by the user. +This process parses all of the header files, and creates a representation of the classes / enums / etc in YAML. Occasionally, some functions might be ignored or need custom pybind code, which can be added to these files by the user. -There is a bazel task that you can run to automatically update the files: +There is a Bazel task that you can run to automatically update the files: `bazel run //wpilibc:write_robotpy-wpilib-update-yaml` ## 3. generate-build-info -This step takes the yaml files, and auto generates a bazel build script for the library. +This step takes the yaml files, and auto-generates a Bazel build script for the library. -There is a bazel task that you can run to automatically update the files: +There is a Bazel task that you can run to automatically update the files: `bazel run //wpilibc:robotpy-wpilib-generator.generate_build_info` ## semiwrap errors -If all of these steps above go smoothly and have their tests pass, but the generated cpp files still won't compile, it is possible that either an update needs to be made to the semiwrap tool to handle the new complex functionality, the new functionality can be ignored, or the new functionality might be better handled with a custom pybind11 implementation. In any case, it is best to reach out to the robotpy team for guidance. +If all of the above steps go smoothly and have their tests pass, but the generated cpp files still won't compile, it is possible that either an update needs to be made to the semiwrap tool to handle the new complex functionality, the new functionality can be ignored, or the new functionality might be better handled with a custom pybind11 implementation. In any case, it is best to reach out to the RobotPy team for guidance. ## Running multiple projects at once Each project has its own `scan-headers` and various pregeneration tools, but you can run all of them at once with the following commands. Note: Sometimes if something in the dependency chain for a library fails, these amalgamation commands will also fail. If that happens, fix your way up the dependency chain project by project. diff --git a/README.md b/README.md index 84bbbfe1761..da7778f20e9 100644 --- a/README.md +++ b/README.md @@ -3,8 +3,9 @@ [![Gradle](https://github.com/wpilibsuite/allwpilib/actions/workflows/gradle.yml/badge.svg?branch=main)](https://github.com/wpilibsuite/allwpilib/actions/workflows/gradle.yml) [![C++ Documentation](https://img.shields.io/badge/documentation-c%2B%2B-blue)](https://github.wpilib.org/allwpilib/docs/development/cpp/) [![Java Documentation](https://img.shields.io/badge/documentation-java-orange)](https://github.wpilib.org/allwpilib/docs/development/java/) +[![Python Documentation](https://img.shields.io/badge/documentation-python-blue)](https://robotpy.readthedocs.io/projects/robotpy/en/latest/) -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. +Welcome to the WPILib project. This repository contains the HAL, CameraServer, Commands (v2 and v3), NTCore, WPIMath, and WPILib projects. These are the core libraries for creating robot programs for Systemcore. - [WPILib Project](#wpilib-project) - [WPILib Mission](#wpilib-mission) @@ -25,7 +26,7 @@ Welcome to the WPILib project. This repository contains the HAL, WPILibJ, and WP ## 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](LICENSE.md). +The WPILib Mission is to enable FIRST Robotics Competition (FRC) and FIRST Tech Challenge (FTC) 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 the FRC Kit of Parts/FTC control system components directly in the library. We also strive to keep parity between major features of each language (Java, C++, and Python), 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](LICENSE.md). # Quick Start @@ -38,7 +39,7 @@ Below is a list of instructions that guide you through cloning, building, publis # 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. +Using Gradle makes building WPILib very straightforward. It only has a few dependencies on outside tools, such as the ARM cross compiler for creating Systemcore binaries. ## Requirements @@ -51,16 +52,13 @@ Using Gradle makes building WPILib very straightforward. It only has a few depen - On Linux, install GCC 11 or greater - On Windows, install [Visual Studio Community 2022](https://visualstudio.microsoft.com/vs/community/) 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 14 or later is required. -- ARM compiler toolchain - - Run `./gradlew installRoboRioToolchain` after cloning this repository - - If the WPILib installer was used, this toolchain is already installed - Raspberry Pi toolchain (optional) - - Run `./gradlew installArm32Toolchain` after cloning this repository + - Run `./gradlew installArm64Toolchain` after cloning this repository - Systemcore toolchain (required for Systemcore development) - Run `./gradlew installSystemCoreToolchain` after cloning this repository - If the WPILib installer was used, this toolchain is already installed -On macOS ARM, run `softwareupdate --install-rosetta`. This is necessary to be able to use the macOS x86 roboRIO toolchain on ARM. +On macOS ARM, run `softwareupdate --install-rosetta`. This is necessary to be able to use the macOS x86 Systemcore toolchain on ARM. On linux, run `sudo apt install libx11-dev libgl-dev libxcursor-dev libxrandr-dev libxinerama-dev libxi-dev` to be able to build things depending on glfw. @@ -183,15 +181,15 @@ If you are building to test with other dependencies or just want to export the b - stable - Publishes to ~/releases/maven/stable. - release - Publishes to ~/releases/maven/release. -The maven artifacts are described in [MavenArtifacts.md](MavenArtifacts.md) +The Maven artifacts are described in [MavenArtifacts.md](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 main WPILib code you're probably looking for is in WPILibJ and WPILibC. Those directories contain the high-level hardware/robot classes used for interacting with hardware, the Driver Station, and contain the core framework that almost all robot projects use. -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 src/test directories under each subproject for C++ and Java contain test code that runs on GitHub Actions. When you submit code for review, it is tested by GitHub Actions' runners. 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](https://github.com/wpilibsuite/ni-libraries) project. +The hal directory contains more C++ code meant to run on Systemcore. HAL is an acronym for "Hardware Abstraction Layer", and it interfaces with the robot controller to enable hardware interactions. The HAL is split into cpp, sim, and systemcore. The systemcore directory contains the WPILib code meant to run on your Systemcore. Sim is WPILib code meant to run on your computer, and cpp is code shared between the two. Code in the cpp directory 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 upstream_utils directory contains scripts for updating copies of thirdparty code in the repository. diff --git a/ThirdPartyNotices.txt b/ThirdPartyNotices.txt index 22c36544fc2..8d203652e53 100644 --- a/ThirdPartyNotices.txt +++ b/ThirdPartyNotices.txt @@ -25,11 +25,6 @@ fmtlib wpiutil/src/main/native/thirdparty/fmtlib/ sigslot wpiutil/src/main/native/thirdparty/sigslot tcpsockets wpinet/src/main/native/thirdparty/tcpsockets MPack wpiutil/src/main/native/thirdparty/mpack -Bootstrap wpinet/src/main/native/resources/bootstrap-* -CoreUI wpinet/src/main/native/resources/coreui-* -Feather Icons wpinet/src/main/native/resources/feather-* -jQuery wpinet/src/main/native/resources/jquery-* -popper.js wpinet/src/main/native/resources/popper-* units wpimath/src/main/native/include/wpi/units/ Eigen wpimath/src/main/native/thirdparty/eigen/include/ Team 254 Library wpimath/src/main/java/org/wpilib/math/spline/SplineParameterizer.java @@ -486,128 +481,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -============================================================================== -Bootstrap License -============================================================================== -Copyright (c) 2011-2018 Twitter, Inc. -Copyright (c) 2011-2018 The Bootstrap Authors - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. - - -============================================================================== -CoreUI License -============================================================================== -Copyright (c) 2018 creativeLabs tukasz Holeczek. - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. - - -============================================================================== -Feather Icons License -============================================================================== -Copyright (c) 2013-2017 Cole Bemis - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. - - -============================================================================== -jQuery License -============================================================================== -Copyright JS Foundation and other contributors, https://js.foundation/ - -Permission is hereby granted, free of charge, to any person obtaining -a copy of this software and associated documentation files (the -"Software"), to deal in the Software without restriction, including -without limitation the rights to use, copy, modify, merge, publish, -distribute, sublicense, and/or sell copies of the Software, and to -permit persons to whom the Software is furnished to do so, subject to -the following conditions: - -The above copyright notice and this permission notice shall be -included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE -LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION -OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION -WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - - -============================================================================== -popper.js License -============================================================================== -Copyright (c) 2016 Federico Zivolo and contributors - -Permission is hereby granted, free of charge, to any person obtaining a copy of -this software and associated documentation files (the "Software"), to deal in -the Software without restriction, including without limitation the rights to -use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies -of the Software, and to permit persons to whom the Software is furnished to do -so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. - - ============= units License ============= diff --git a/apriltag/README.md b/apriltag/README.md index ade440940ef..644b95547e4 100644 --- a/apriltag/README.md +++ b/apriltag/README.md @@ -1,10 +1,12 @@ # AprilTag +A C++ wrapper around the [University of Michigan's AprilTag detector](https://github.com/AprilRobotics/apriltag), alongside a vendored copy of their code with some patches (patches are located in [upstream_utils](../upstream_utils/apriltag_patches/)). + ## Adding new field to AprilTagFields ### Adding field JSON -1. Add a field layout CSV file to `src/main/native/resources/edu/wpi/first/apriltag` +1. Add a field layout CSV file to `src/main/native/resources/org/wpilib/vision/apriltag` 1. See docstring in `convert_apriltag_layouts.py` for more 2. Run `convert_apriltag_layouts.py` in the same directory as this readme to generate the JSON 3. That script overwrites all generated JSONs, so undo undesired changes if necessary @@ -14,7 +16,7 @@ ### Java updates -1. Update `src/main/java/edu/wpi/first/apriltag/AprilTagFields.java` +1. Update `src/main/java/org/wpilib/vision/apriltag/AprilTagFields.java` 1. Add enum value for new field to `AprilTagFields` 2. Update `AprilTagFields.kDefaultField` if necessary @@ -23,6 +25,6 @@ 1. Update `src/main/native/include/wpi/apriltag/AprilTagFields.hpp` 1. Add enum value for new field to `AprilTagFields` 2. Update `AprilTagFields::kDefaultField` if necessary -2. Update `src/main/native/cpp/AprilTagFields.cpp` +2. Update `src/main/native/cpp/AprilTagFieldLayout.cpp` 1. Add resource getter prototype like `std::string_view GetResource_2024_crescendo_json()` - 2. Add case for new field to switch in `LoadAprilTagLayoutField()` + 2. Add case for new field to switch in `LoadField(AprilTagField field)` diff --git a/benchmark/README.md b/benchmark/README.md index 164ba024461..63af5dc50c7 100644 --- a/benchmark/README.md +++ b/benchmark/README.md @@ -16,7 +16,7 @@ This command runs the C++ benchmarks on desktop. ./gradlew benchmark:runCpp ``` -## Deploy to a roboRIO +## Deploy to a Systemcore This project can only deploy over USB. If an alternate IP address is preferred, the `address` block in benchmark/build.gradle can be changed to point to another address. @@ -30,7 +30,7 @@ This command deploys the C++ project with all dependencies statically linked. ./gradlew benchmark:deployStatic ``` -This command deploys the Java project and all required dependencies. It also installs the JRE if it's not currently installed. +This command deploys the Java project and all required dependencies. ```bash ./gradlew benchmark:deployJava ``` @@ -42,7 +42,7 @@ ssh lvuser@172.22.11.2 frcRunRobot.sh Console log prints will appear in the terminal. -Deploying any of these to the roboRIO will disable the current startup project until it is redeployed. +Deploying any of these to a Systemcore will disable the current startup project until it is redeployed. ## Faster builds diff --git a/datalog/README.md b/datalog/README.md new file mode 100644 index 00000000000..6364c8af2a3 --- /dev/null +++ b/datalog/README.md @@ -0,0 +1,5 @@ +# datalog + +DataLog is a simple, fast, binary logging format designed to be more advanced than logging converting values to strings, while maintaining speed on embedded platforms. More about the motivation can be found in [the DataLog format specification](./doc/datalog.adoc). + +Also see [the Kaitai Struct file](./doc/wpilog.ksy), which uses [Kaitai Struct](https://kaitai.io/) to declaratively describe the DataLog format and allows for generating libraries in other languages to parse DataLog files. diff --git a/developerRobot/README.md b/developerRobot/README.md index 8aa24792526..841ebc314c1 100644 --- a/developerRobot/README.md +++ b/developerRobot/README.md @@ -1,6 +1,6 @@ # Developer Robot -This is a robot project built directly against this repo's sources. It builds the minimum required for deploying to a roboRIO, so it's faster than publishing the whole library to Maven first. +This is a robot project built directly against this repo's sources. It builds the minimum required for deploying to a Systemcore, so it's faster than publishing the whole library to Maven first. This command builds everything. ```bash @@ -19,7 +19,7 @@ This command runs the C++ project on desktop. ./gradlew developerRobot:runCpp ``` -## Deploy to a roboRIO +## Deploy to a Systemcore This project can only deploy over USB. If an alternate IP address is preferred, the `address` block in developerRobot\build.gradle can be changed to point to another address. @@ -33,7 +33,7 @@ This command deploys the C++ project with all dependencies statically linked. ./gradlew developerRobot:deployStatic ``` -This command deploys the Java project and all required dependencies. It also installs the JRE if it's not currently installed. +This command deploys the Java project and all required dependencies. ```bash ./gradlew developerRobot:deployJava ``` @@ -46,4 +46,4 @@ ssh systemcore@172.22.11.2 sudo ~/robotCommand Console log prints will appear in the terminal. -Deploying any of these to the roboRIO will disable the current startup project until it is redeployed. +Deploying any of these to a Systemcore will disable the current startup project until it is redeployed. diff --git a/epilogue-processor/README.md b/epilogue-processor/README.md new file mode 100644 index 00000000000..4c173ea4ada --- /dev/null +++ b/epilogue-processor/README.md @@ -0,0 +1,3 @@ +# epilogue-processor + +Epilogue is an Java annotation-based telemetry library designed to provide easier interactions with WPILib's telemetry and logging facilities in robot projects, most notably, NetworkTables and DataLog. Usage docs can be found at https://docs.wpilib.org/en/latest/docs/software/telemetry/robot-telemetry-with-annotations.html. This subproject provides the annotation processor to generate code for publishing/logging data. diff --git a/epilogue-runtime/README.md b/epilogue-runtime/README.md new file mode 100644 index 00000000000..b30cd2af3fc --- /dev/null +++ b/epilogue-runtime/README.md @@ -0,0 +1,3 @@ +# epilogue-runtime + +Epilogue is an Java annotation-based telemetry library designed to provide easier interactions with WPILib's telemetry and logging facilities in robot projects, most notably, NetworkTables and DataLog. Usage docs can be found at https://docs.wpilib.org/en/latest/docs/software/telemetry/robot-telemetry-with-annotations.html. This subproject provides the runtime library used by the generated Epilogue code to configure Epilogue's behavior. diff --git a/fields/README.md b/fields/README.md new file mode 100644 index 00000000000..852f033bcfe --- /dev/null +++ b/fields/README.md @@ -0,0 +1,49 @@ +# fields + +The library where FIRST field images and their metadata are stored for use by other programs. + +## Adding new field images + +### Adding the image + +Field images, if stored in PNG format, should be compressed with [oxipng](https://github.com/oxipng/oxipng) using `oxipng -o max --fast --strip safe -z fieldImage.png` to ensure the image is as small as possible. They should then be placed in `src/main/native/resources/org/wpilib/fields/`, with the name `YEAR-gamename`, with `` being either `ftc` or `frc`. For FTC, the year is a pair of years, like `2025-2026`. + +### Adding the JSON + +A JSON file with the same name should also be placed in the same location, with 6 fields: + +- `game`, which should be the name of the game +- `field-image`, which contains the path of the field image relative to the directory containing the JSON file +- `field-corners`, an object that contains the two fields `top-left` and `bottom-right`, which are pairs of XY coordinates specifying the boundaries of the field in pixels +- `field-size`, which is a pair of lengths in the X and Y axes, respectively +- `field-unit`, the unit for `field-size` (always "foot") +- `program`, which is either `ftc` or `frc` + +X is 0 at the left edge and increases to the right, and Y is 0 at the top edge and increases going down. + +### Java updates + +Add a new enum value to `src/main/java/org/wpilib/fields/Fields.java`. The enum value will be the path to the field JSON relative to the base resource directory stored in the enum. + +### C++ updates + +Create a new header in `src/main/native/include/wpi/fields/` called `YEAR-gamename.hpp`, and fill in this template with the year and game name. + +```c++ +// Copyright (c) FIRST and other WPILib contributors. +// Open Source Software; you can modify and/or share it under the terms of +// the WPILib BSD license file in the root directory of this project. + +#pragma once + +#include + +namespace wpi::fields { +std::string_view GetResource___json(); +std::string_view GetResource___png(); +} // namespace wpi::fields +``` + +For FTC, `` should have the dash replaced with an underscore. + +Finally, add the new field to the to the list of fields in `src/main/native/cpp/fields.cpp`, including the newly added header and using the functions inside. diff --git a/javacPlugin/README.md b/javacPlugin/README.md new file mode 100644 index 00000000000..c70a11bd9ac --- /dev/null +++ b/javacPlugin/README.md @@ -0,0 +1,7 @@ +# javacPlugin + +A javac plugin for use in WPILib and WPILib robot projects. Combined with [wpiannotations](../wpiannotations/README.md), this plugin analyzes source code to ensure the constraints laid out by the specified annotations are followed (to the extent static analysis allows) in order to reduce user mistakes. + +## Design guidelines + +This plugin should only be used for static analysis, not to enhance the Java language with syntax features. Adding additional syntax features is outside the scope of this plugin and can be confusing to beginners. diff --git a/ntcore/README.md b/ntcore/README.md new file mode 100644 index 00000000000..eca26ab6310 --- /dev/null +++ b/ntcore/README.md @@ -0,0 +1,5 @@ +# ntcore + +ntcore is a library for using NetworkTables. To learn more about what NetworkTables is, read https://docs.wpilib.org/en/latest/docs/software/networktables/networktables-intro.html. + +If you're a developer looking for the NetworkTables protocol specifications, take a look at [the doc folder](./doc). diff --git a/simulation/README.md b/simulation/README.md index 95c3fb8b08e..755403fe98b 100644 --- a/simulation/README.md +++ b/simulation/README.md @@ -1,7 +1,7 @@ # Simulation Extensions This is where WPILib's simulation extensions are housed. Simulation extensions are referred to by various names: simulation plugins, simulation modules, sim extensions, HALSIM extensions, but they all refer to the same thing, which are dynamically loaded libraries that can use HALSIM functions to register callbacks that update HAL data. The robot program loads simulation extensions by looking for the `HALSIM_EXTENSIONS` environment variable, which contains the paths to the libraries separated by colons on Linux/Mac, and semicolons on Windows. -# Writing a custom simulation extension +## Writing a custom simulation extension All simulation extensions contain a `int HALSIM_InitExtension(void)` function, which is the entry point. The function declaration should look like this: ```c++ @@ -16,23 +16,23 @@ int HALSIM_InitExtension(void) { The function is contained with an `extern "C"` block so it can be called by the robot program and has `__declspec(dllexport)` for Windows. From here, you can interface with the HAL to provide data. -## Extension registration +### Extension registration Extensions can register themselves by calling `HAL_RegisterExtension`. This will register the extension's name, and a pointer to some sort of data. A separate extension can listen for extension registration by calling `HAL_RegisterExtensionListener`. It takes a callback accepting the data initially passed into `HAL_RegisterExtension`. This can be used to detect if a specific extension was loaded, and take action if it was. Note that extensions must opt-in to registration; extensions that do not register will not trigger the registration listener. -## Using HALSIM functions +### Using HALSIM functions Several devices in the HAL have functions that allow you to feed data from an external source into the HAL. The full list can be found in the HAL subdirectory in `include/hal/simulation`. For example, the AccelerometerData header declares functions that update the X, Y, and Z axes with data. Some functions accept callbacks; the I2CData header declares functions which accept other functions with parameters that allow it to accept data. This allows the implementation of a simulation extension that interfaces with an I2C bus and connects it to the HAL, allowing the use of real I2C hardware in simulation. Note that these callbacks are called synchronously and in the same thread as the robot program; long delays in callbacks will block the main thread and can cause loop overruns. -## Building the extension -To build an extension for use in a robot project, you'll need to build with Gradle. The easiest way to get a working build.gradle file is to copy the build.gradle file from halsim_xrp. It doesn't have any tests, and it only depends on halsim_ws_core. The important line is `lib project: ':wpinet', library: 'wpinet', linkage: 'shared'`. This tells Gradle to link the extension with wpinet using shared libraries. Other libraries can be included in a similar way by referencing the Gradle subproject name. Note that you do not need to include the HAL since it is automatically included. +### Building a new extension +To build an extension for use in a robot project, you'll need to add a new Gradle subproject. The easiest way to get a working build.gradle file is to copy the build.gradle file from halsim_xrp. It doesn't have any tests, and it only depends on halsim_ws_core. The important line is `lib project: ':wpinet', library: 'wpinet', linkage: 'shared'`. This tells Gradle to link the extension with wpinet using shared libraries. Other libraries can be included in a similar way by referencing the Gradle subproject name. Note that you do not need to include the HAL since it is automatically included. You'll also need to modify settings.gradle to include your new subproject. Building any given extension can be done using the `simulation:folder_name:build`. -# Using a custom extension +### Using a custom extension After setting up a build.gradle file for a custom extension, follow the guides to build and publish your own local build of allwpilib. Once you've published a local build, follow the instructions in [DevelopmentBuilds.md](/DevelopmentBuilds.md) to use the locally published build in a robot project. Then, place this line your robot project's build.gradle file: ```groovy wpi.sim.addDep("Custom Sim Extension", "org.wpilib.halsim", "pluginName") ``` where `Custom Sim Extension` is the name of the extension shown by VS Code and `pluginName` is the same as `pluginName` declared in the build.gradle file for the simulation extension. -# Built-in extensions +## Built-in extensions halsim_ds_socket: Allows the real Driver Station to control the robot program. halsim_gui: Provides the simulation GUI. diff --git a/simulation/halsim_ds_socket/README.md b/simulation/halsim_ds_socket/README.md index c8f307838b1..a1dde08a192 100644 --- a/simulation/halsim_ds_socket/README.md +++ b/simulation/halsim_ds_socket/README.md @@ -1,6 +1,6 @@ # HAL DS Socket This is an extension that allows the Driver Station to communicate with the robot program. Note that not everything has been reimplemented, since lots of DS data like battery voltage doesn't apply in simulation. -# Configuration +## Configuration The only environment variable the extension supports is `DS_TIMEOUT_MS`, which is the amount of milliseconds it takes for a UDP packet to arrive from the DS before the robot program automatically disables. Default value is `100`, representing 100 milliseconds. diff --git a/tools/sysid/docs/data-collection.md b/tools/sysid/docs/data-collection.md deleted file mode 100644 index 538aff40cb9..00000000000 --- a/tools/sysid/docs/data-collection.md +++ /dev/null @@ -1,210 +0,0 @@ -# Data Collection - -This document details how data must be sent over NetworkTables for accurate data collection. Note that the data format has changed from what the old [frc-characterization](https://github.com/wpilibsuite/frc-characterization) tool used to generate. - -## NetworkTables Data Entries - -Here is a list of the NT entries that are used to send and collect data between sysid and the robot program: - -| NT Entry | Type | Description | -| --------------------------------------| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/SmartDashboard/SysIdTelemetry` | `string` | Used to send telemetry from the robot program. This data is sent after the test completes once the robot enters the disabled state. | -| `/SmartDashboard/SysIdVoltageCommand` | `double` | Used to either send the ramp rate (V/s) for the quasistatic test or the voltage (V) for the dynamic test. | -| `/SmartDashboard/SysIdTestType` | `string` | Used to send the test type ("Quasistatic" or "Dynamic") which helps determine how the `VoltageCommand` entry will be used. | -| `/SmartDashboard/SysIdRotate` | `bool` | Used to receive the rotation bool from the Logger. If this is set to true, the drivetrain will rotate. It is only applicable for drivetrain tests. | - -## Telemetry Format - -There are two formats used to send telemetry from the robot program. One format is for non-drivetrain mechanisms, whereas the other is for all drivetrain tests (linear and angular). All timestamps must be in seconds. - -### Non-Drivetrain Mechanisms - -`timestamp, voltage, position, velocity` - -Example JSON: - -```json -{ -"fast-backward": [ -[ -timestamp 1, -voltage 1, -position 1, -velocity 1 -], -[ -timestamp 2, -voltage 2, -position 2, -velocity 2 -] -], -"fast-forward": [ -[ -timestamp 1, -voltage 1, -position 1, -velocity 1 -], -[ -timestamp 2, -voltage 2, -position 2, -velocity 2 -] -], -"slow-backward": [ -[ -timestamp 1, -voltage 1, -position 1, -velocity 1 -], -[ -timestamp 2, -voltage 2, -position 2, -velocity 2 -] -], -"slow-forward": [ -[ -timestamp 1, -voltage 1, -position 1, -velocity 1 -], -[ -timestamp 2, -voltage 2, -position 2, -velocity 2 -] -], -"sysid": true, -"test": "Simple", -"units": "Rotations", -"unitsPerRotation": 1.0 -} -``` - -Supported test types for the "test" field in this data format include "Arm", -"Elevator", and "Simple". Supported unit types include "Meters", "Feet", -"Inches", "Radians", "Rotations", and "Degrees". - -### Drivetrain - -`timestamp, l voltage, r voltage, l position, r position, l velocity, r velocity, angle, angular rate` - -Note that all positions and velocities should be in rotations of the output and rotations/sec of the output respectively. If there is a gearing between the encoder and the output, that should be taken into account. - -Example JSON: - -```json -{ -"fast-backward": [ -[ -timestamp 1, -l voltage 1, -r voltage 1, -l position 1, -r position 1, -l velocity 1, -r velocity 1, -angle 1, -angular rate 1 -], -[ -timestamp 2, -l voltage 2, -r voltage 2, -l position 2, -r position 2, -l velocity 2, -r velocity 2, -angle 2, -angular rate 2 -] -], -"fast-forward": [ -[ -timestamp 1, -l voltage 1, -r voltage 1, -l position 1, -r position 1, -l velocity 1, -r velocity 1, -angle 1, -angular rate 1 -], -[ -timestamp 2, -l voltage 2, -r voltage 2, -l position 2, -r position 2, -l velocity 2, -r velocity 2, -angle 2, -angular rate 2 -] -], -"slow-backward": [ -[ -timestamp 1, -l voltage 1, -r voltage 1, -l position 1, -r position 1, -l velocity 1, -r velocity 1, -angle 1, -angular rate 1 -], -[ -timestamp 2, -l voltage 2, -r voltage 2, -l position 2, -r position 2, -l velocity 2, -r velocity 2, -angle 2, -angular rate 2 -] -], -"slow-forward": [ -[ -timestamp 1, -l voltage 1, -r voltage 1, -l position 1, -r position 1, -l velocity 1, -r velocity 1, -angle 1, -angular rate 1 -], -[ -timestamp 2, -l voltage 2, -r voltage 2, -l position 2, -r position 2, -l velocity 2, -r velocity 2, -angle 2, -angular rate 2 -] -], -"sysid": true, -"test": "Drivetrain", -"units": "Rotations", -"unitsPerRotation": 1.0 -} -``` - -Supported test types for the "test" field in this data format include -"Drivetrain" and "Drivetrain (Angular)". Supported unit types include "Meters", -"Feet", "Inches", "Radians", "Rotations", and "Degrees". diff --git a/wpiannotations/README.md b/wpiannotations/README.md new file mode 100644 index 00000000000..60d547e9656 --- /dev/null +++ b/wpiannotations/README.md @@ -0,0 +1,3 @@ +# wpiannotations + +A collection of annotations for use in WPILib (and WPILib robot projects), used in conjunction with [javacPlugin](../javacPlugin/README.md) to do compile time static analysis. These annotations allow constraints to be placed on code to prevent user mistakes (by emitting compiler errors when common error patterns are detected). diff --git a/wpigui/README.md b/wpigui/README.md new file mode 100644 index 00000000000..3f2913a7d18 --- /dev/null +++ b/wpigui/README.md @@ -0,0 +1,9 @@ +# wpigui + +A [Dear Imgui](https://github.com/ocornut/imgui) wrapper that handles platform-specifics like the rendering API and adds some convenience functions. Bootstrap an app with three lines: + +```c++ +wpi::gui::CreateContext(); +wpi::gui::Initialize("Hello World", 1024, 768); +wpi::gui::Main(); +```