https://github.com/wpilibsuite/native-utils
Gradle utility plugin for compiling native libraries
https://github.com/wpilibsuite/native-utils
Last synced: about 1 month ago
JSON representation
Gradle utility plugin for compiling native libraries
- Host: GitHub
- URL: https://github.com/wpilibsuite/native-utils
- Owner: wpilibsuite
- License: other
- Created: 2017-07-27T02:20:34.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2025-04-05T19:13:56.000Z (about 2 months ago)
- Last Synced: 2025-04-14T12:05:14.721Z (about 1 month ago)
- Language: Java
- Size: 1.16 MB
- Stars: 4
- Watchers: 7
- Forks: 22
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- License: license.txt
Awesome Lists containing this project
README
# Native Utils and Toolchain Plugin
## DSL Documentation for Native Utils
```
nativeUtils {
platformConfigs {
linuxathena {
// The platform path for archives. Must be set
platformPath = "linux/athena"
cppCompiler {
// Args for debug and release
args << ""
// Args for debug
debugArgs << ""
// Args for release
releaseArgs << ""
}
// These are identical to cppCompiler
linker {}
cCompiler {}
assembler {}
objcppCompiler {}
objcCompiler {}
}
}
// Windows specific functionality to export all symbols from a binary automatically
exportsConfigs {
libName {
x86ExcludeSymbols << ""
x64ExcludeSymbols << ""
excludeBuildTypes << ""
x86SymbolFilter = { symbols ->
symbols.removeIf({ !it.startsWith('HAL_') && !it.startsWith('HALSIM_') })
}
x64SymbolFilter = { symbols ->
symbols.removeIf({ !it.startsWith('HAL_') && !it.startsWith('HALSIM_') })
}
}
}
// Multi platform way to expose only a limited number of symbols
// Used to do private symbols. Can not cross libraries with exportsConfigs
privateExportsConfigs {
libName {
exportsFile = project.file("path/to/symbols/files")
}
}
// Add a dependency
dependencyConfigs {
libraryName {
groupId = ""
artifactId = ""
headerClassifier = ""
sourceClassifier = ""
ext = ""
version = ""
// If the shared dependencies are used at runtime, or just linking
// Defaults to true
sharedUsedAtRuntime = true
sharedPlatforms << ""
staticPlatforms << ""
}
}
// Add
combinedDependencyConfigs {
combinedName {
// The name to use from use*Library
libraryName = ""
// The platforms to apply to
targetPlatforms << ""
// The dependencies to combine
dependencies << ""
}
}
}
// Get the platform path for a binary
nativeUtils.getPlatformPath(NativeBinarySpec binary)
// Get the classifier for a dependency
nativeUtils.getDependencyClassifier(NativeBinarySpec, boolean isStaticDependnecy)
// Get the classifier for a published binary
nativeUtils.getPublishClassifier(NativeLibraryBinarySpec)
// Add libraries that are required to build, add to all binaries for a component
nativeUtils.useRequiredLibrary(ComponentSpec, String... libraries)
// Add libraries that are required to build, add to specific binary
nativeUtils.useRequiredLibrary(BinarySpec, String.. libraries)
// Add libraries that are optional, add to all binaries for a component
nativeUtils.useOptionalLibrary(ComponentSpec, String... libraries)
// Add libraries that are optional, add to specific binary
nativeUtils.useOptionalLibrary(BinarySpec, String.. libraries)
// The optional ones will be silently skipped
// Add all native utils platforms to a component
nativeUtils.useAllPlatforms(ComponentSpec)
// Update a platform (see platformsConfig block above for documentation)
// This can be used for adding or removing args.
nativeUtils.configurePlatform("platformName") {
}
// Add all arguments for a platform to the binary
nativeUtils.usePlatformArguments(NativeBinarySpec)
// Add all arguments for a platform to all components of a binary
nativeUtils.usePlatformArguments(NativeComponentSpec)
// Add WPI extensions to Native Utils
// See below for DSL of these extensions
nativeUtils.addWpiNativeUtils()
// This adds all the WPILib dependencies, along with combined deps for
// wpilib and driver. They still need to manually be added to individual
// components. These just add to the back end
nativeUtils.wpi.configureDependencies {
// Thse are the 6 separate versions used for wpi
// deps. They should be kept in sync.
wpiVersion = ""
niLibVersion = ""
opencvVersion = ""
}
// The 6 below get the string representation of the main platforms
// For use comparing to binary.targetPlatform.name
nativeUtils.wpi.platforms.roborio
nativeUtils.wpi.platforms.linuxarm32
nativeUtils.wpi.platforms.linuxarm64
nativeUtils.wpi.platforms.systemcore
nativeUtils.wpi.platforms.windowsx64
nativeUtils.wpi.platforms.osxuniversal
nativeUtils.wpi.platforms.linuxx64
// An immutable list of all wpi platforms
nativeUtils.wpi.platforms.allPlatforms
// A bunch of lists of the default arguments for platforms.
nativeUtils.wpi.defaultArguments.*
// Enable warnings for all platforms. Pass specific platforms in to enable them for just those platforms
nativeUtils.wpi.addWarnings()
// Enable warnings as errors for all platforms. Pass specific platforms in to enable them for just those platforms
// Does not enable warnings, that is still handled by the call above.
nativeUtils.wpi.addWarningsAsErrors()
```
## DS Documentation for Toolchain Builder
```
toolchainsPlugin {
// Register the platforms and build types with the model
// Default to true
registerPlatforms = true
registerReleaseBuildType = true
registerDebugBuildType = true
// Add the roborio compiler
withCrossRoboRIO()
// Add the raspbian compiler
withCrossLinuxArm32()
// The above 2 are included with nativeUtils.addWpiNativeUtils()
crossCompilers {
linuxaarch64 {
architecture = "aarch64"
compilerPrefix = "arm-frc2019-linux-gnueabi-"
operatingSystem = "linux"
optional = false
}
}
}
```
## Adding a non standard cross compiler
Use the following to add a custom cross compiler, with the same args as the rio and raspbian
```
nativeUtils.addWpiNativeUtils() // Must be called before using nativeUtils.wpi.defaultArguments
toolchainsPlugin.crossCompilers {
linuxaarch64 {
architecture = "aarch64"
compilerPrefix = "aarch64-linux-gnu-"
operatingSystem = "linux"
optional = false
}
}
nativeUtils.platformConfigs {
linuxaarch64 {
platformPath = "linux/aarch64"
cppCompiler.args.addAll(nativeUtils.wpi.defaultArguments.linuxCrossCompilerArgs);
cCompiler.args.addAll(nativeUtils.wpi.defaultArguments.linuxCrossCCompilerArgs);
linker.args.addAll(nativeUtils.wpi.defaultArguments.linuxCrossLinkerArgs);
cppCompiler.debugArgs.addAll(nativeUtils.wpi.defaultArguments.linuxCrossDebugCompilerArgs);
cppCompiler.releaseArgs.addAll(nativeUtils.wpi.defaultArguments.linuxCrossReleaseCompilerArgs);
}
}
```
# Using custom builds
To use a custom build of native-utils in a robot project, the build must be published, and a GradleRIO build that uses the new version must be pulished.
1. Update the version in `build.gradle` so that native-utils won't overwrite an existing version.
```
allprojects {
group = "edu.wpi.first"
version = "2024.3.1"
```
2. Execute `.\gradlew publishToMavenLocal`
3. Update native-utils version in GradleRIO ``build.gradle``: ``api 'edu.wpi.first:native-utils:2024.3.1'``
4. Follow the directions in the  for publishing a local build and using in a robot program