From 291916d7ae52a553c72c15bd5b4e653ca1aeddbc Mon Sep 17 00:00:00 2001 From: Daltz333 Date: Thu, 11 Feb 2021 11:49:32 -0500 Subject: [PATCH 1/4] Add external libraries article --- .../basic-programming/external-libraries.rst | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 source/docs/software/basic-programming/external-libraries.rst diff --git a/source/docs/software/basic-programming/external-libraries.rst b/source/docs/software/basic-programming/external-libraries.rst new file mode 100644 index 0000000000..1ad5e43fc4 --- /dev/null +++ b/source/docs/software/basic-programming/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 `__. From 367859b28a70ad7100b15501e1c797677d7c6d34 Mon Sep 17 00:00:00 2001 From: Daltz333 Date: Thu, 11 Feb 2021 11:53:12 -0500 Subject: [PATCH 2/4] Add to TOCTREE --- source/docs/software/basic-programming/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/docs/software/basic-programming/index.rst b/source/docs/software/basic-programming/index.rst index d4bc500399..a72366a980 100644 --- a/source/docs/software/basic-programming/index.rst +++ b/source/docs/software/basic-programming/index.rst @@ -7,3 +7,4 @@ Basic Programming git-getting-started.rst cpp-units robot-code-ci + external-libraries From 0343bbc2c5e8a47d85eb7bc7d7d3bfb52f7238a5 Mon Sep 17 00:00:00 2001 From: Daltz333 Date: Thu, 11 Feb 2021 11:57:50 -0500 Subject: [PATCH 3/4] Move to it's own section --- .../external-libraries.rst | 0 source/docs/software/advanced-gradlerio/index.rst | 7 +++++++ source/docs/software/basic-programming/index.rst | 1 - source/index.rst | 1 + 4 files changed, 8 insertions(+), 1 deletion(-) rename source/docs/software/{basic-programming => advanced-gradlerio}/external-libraries.rst (100%) create mode 100644 source/docs/software/advanced-gradlerio/index.rst diff --git a/source/docs/software/basic-programming/external-libraries.rst b/source/docs/software/advanced-gradlerio/external-libraries.rst similarity index 100% rename from source/docs/software/basic-programming/external-libraries.rst rename to source/docs/software/advanced-gradlerio/external-libraries.rst diff --git a/source/docs/software/advanced-gradlerio/index.rst b/source/docs/software/advanced-gradlerio/index.rst new file mode 100644 index 0000000000..01b5539a4d --- /dev/null +++ b/source/docs/software/advanced-gradlerio/index.rst @@ -0,0 +1,7 @@ +Advanced GradleRIO Configuration +================================ + +.. toctree:: + :maxdepth: 1 + + external-libraries diff --git a/source/docs/software/basic-programming/index.rst b/source/docs/software/basic-programming/index.rst index a72366a980..d4bc500399 100644 --- a/source/docs/software/basic-programming/index.rst +++ b/source/docs/software/basic-programming/index.rst @@ -7,4 +7,3 @@ Basic Programming git-getting-started.rst cpp-units robot-code-ci - external-libraries 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 From 814fa21cf9944fbf131fbc3fc2233f78af2d9f96 Mon Sep 17 00:00:00 2001 From: Daltz333 Date: Thu, 11 Feb 2021 12:10:22 -0500 Subject: [PATCH 4/4] Add GradleRIO predeploy article --- .../software/advanced-gradlerio/index.rst | 1 + .../advanced-gradlerio/predeploy-tasks.rst | 34 +++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 source/docs/software/advanced-gradlerio/predeploy-tasks.rst diff --git a/source/docs/software/advanced-gradlerio/index.rst b/source/docs/software/advanced-gradlerio/index.rst index 01b5539a4d..c6ab00f68c 100644 --- a/source/docs/software/advanced-gradlerio/index.rst +++ b/source/docs/software/advanced-gradlerio/index.rst @@ -5,3 +5,4 @@ Advanced GradleRIO Configuration :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.