diff --git a/source/docs/software/advanced-gradlerio/external-libraries.rst b/source/docs/software/advanced-gradlerio/external-libraries.rst new file mode 100644 index 0000000000..1ad5e43fc4 --- /dev/null +++ b/source/docs/software/advanced-gradlerio/external-libraries.rst @@ -0,0 +1,62 @@ +Using External Libraries with Robot Code +======================================== + +.. warning:: Using external libraries may have unintended behavior with your robot code! It is not recommended unless you are aware of what you are doing! + +Often a team might want to add external Java or C++ libraries for usage with their robot code. This article highlights adding Java libraries to your gradle dependencies, or the options that C++ teams have. + +Java +---- + +.. note:: Any external dependencies that rely on native libraries (JNI) are likely not going to work. + +Java is quite simple to add external dependencies. You simply add the required ``repositories`` and ``dependencies``. + +Robot projects by default do not have a ``repositories {}`` block in the ``build.gradle`` file. You will have to add this yourself. Above the ``dependencies {}`` block, please add the following: + +.. code-block:: groovy + + repositories { + mavenCentral() + ... + } + +``mavenCentral()`` can be replaced with whatever repository the library you want to import is using. Now you have to add the dependency on the library itself. This is done by adding the necessary line to your ``dependencies {}`` block. The below example showcases adding Apache Commons to your gradle project. + +.. code-block:: groovy + + dependencies { + implementation 'org.apache.commons:commons-lang3:3.6' + ... + } + +Now you run a build and ensure the dependencies are downloaded. Intellisense may not work properly until a build is ran! + +C++ +--- + +Adding C++ dependencies to your robot project is non-trivial due to needing to compile for the roboRIO. You have a couple of options. + +1. Copy the source code of the wanted library into your robot project. +2. Use the `vendordep template `__ as an example and create a vendordep. + +Copying Source Code +^^^^^^^^^^^^^^^^^^^ + +Simply copy the necessary source and/or headers into your robot project. You can then configure any necessary platform args like below: + +.. code-block:: groovy + + nativeUtils.platformConfigs.named("linuxathena").configure { + it.cppCompiler.args.remove('-g') + } + + nativeUtils.platformConfigs.named("linuxx86-64").configure { + it.cppCompiler.args.remove('-g') + it.linker.args.add('-lstdc++fs') // links in C++ filesystem library + } + +Creating a Vendordep +^^^^^^^^^^^^^^^^^^^^ + +Please follow the instructions in the `vendordep repository `__. diff --git a/source/docs/software/advanced-gradlerio/index.rst b/source/docs/software/advanced-gradlerio/index.rst new file mode 100644 index 0000000000..c6ab00f68c --- /dev/null +++ b/source/docs/software/advanced-gradlerio/index.rst @@ -0,0 +1,8 @@ +Advanced GradleRIO Configuration +================================ + +.. toctree:: + :maxdepth: 1 + + external-libraries + adding-cpp-compiler-args diff --git a/source/docs/software/advanced-gradlerio/predeploy-tasks.rst b/source/docs/software/advanced-gradlerio/predeploy-tasks.rst new file mode 100644 index 0000000000..2ade89ba23 --- /dev/null +++ b/source/docs/software/advanced-gradlerio/predeploy-tasks.rst @@ -0,0 +1,34 @@ +Adding Predeploy Tasks +====================== + +.. warning:: Adding predeploy tasks can cause some unintended behavior! + +Adding predeploy tasks are useful when the user needs to configure some external program on the roboRIO before deploying robot code. It's also useful for other advanced configurations. + +Add a ``deploy {}`` block to your ``build.gradle`` using the below as an example: + +.. code-block:: groovy + + deploy { + ... + artifacts { + frcNativeArtifact('frcCpp') { + ... + predeploy << { + // Give RT capability + it.execute('setcap cap_sys_nice+eip /home/lvuser/frcUserProgram') + + // Disable crond because it uses 50% CPU and there's no cronjobs to run + it.execute('/etc/init.d/crond stop') + + // Disable NI web server because it leaks memory + it.execute('/usr/local/natinst/etc/init.d/systemWebServer stop') + + // Compress old log files + it.execute('find . -type f | grep \\.csv$ | xargs -d \\n gzip -q') + } + } + } + } + +The above commands will run *after* the robot program is deleted but *before* the new robot program is deployed. diff --git a/source/index.rst b/source/index.rst index 64e7153178..681835dcfb 100644 --- a/source/index.rst +++ b/source/index.rst @@ -74,6 +74,7 @@ Welcome to the *FIRST*\ |reg| Robotics Competition Control System Documentation! docs/software/kinematics-and-odometry/index docs/software/networktables/index docs/software/roborio-info/index + docs/software/advanced-gradlerio/index docs/software/advanced-controls/index docs/software/convenience-features/index