<
>
<
>
<
>
<
>

Create a component

Create a component

install cookiecutter

The easiest way to create a new component is to use our templates. SolAR templates are based on cookiecutter python package (see http://cookiecutter.readthedocs.io).

To install cookiecutter, simply run:

pip install cookiecutter

Windows users: pip is located under the scripts folder of your python3 directory. Usually C:\python3\scripts.

get the templates

Run the following command to get SolAR templates:

git clone ssh://gitolite@forge.b-com.com/argo/tools/templates.git
cd templates

component

In order to create a new component, all you have to do is run this command, and follow the instructions:

$ python template_component/cookiecutter_runner.py

package

In SolAR, components are wrapped into a library that we call a package. You can add you component into an existing package project, or create a brand new package projet. Creating a package is easy based on SolAR templates. Run this command, and follow the instructions:

$ python template_package/cookiecutter_runner.py

finalizing installation

In order to use your component / package, do not forget:

  1. that a BCOMDEVROOT (without backslashes on windows) environment variable must be set, pointing to your installation folder

  2. that an XPCF_REGISTRY_PATH environment variable must be set, pointing to the packages XML file

  3. the XML file itself must be modified, depending on your installation: precisely you will have to set the path to your package library

How to create your Unit Test

Write your unit test

Define unit tests, based on boost framework . You can know more about boost with this link : http://www.boost.org

Your Unit tests for a specific component, should be placed in the component directory/unittest. If you have used the SolARComponent template, this directory should be already there.

Unit test directory

  • Open {yourcomponent}/unittest/{yourcomponent}unittest.pro

  • You have to describe your unit tests in the file {yourcomponent}unittest.cpp

For example

#define
BOOST_TEST_MODULE \{Yourcomponent}UnitTest

#include <boost/test/unit_test.hpp> (1)
#BOOST_AUTO_TEST_CASE(TestLoadImage) (2)
{ // test execution instructions
}
1 Please note your code contains include of boost
2 You have to define the name of your test thanks to the boost macro "BOOST_AUTO_TEST_CASE".

In this example , the definition of the test case "TestLoadImage" for your component.

It means, that when you will execute the unit test, it will executes this test "TestLoadImage" following the instructions in this declaration. You can define several test cases.

Inside your test, please write a kind of demo main function, but where you check results of your component function thanks to macro BOOST CHECK and/or BOOST_TEST.

You will find easily information about BOOST macro on Internet http://www.boost.org/doc/libs/1_64_0/libs/test/doc/html/index.html [boost.org information,role="external", window="_blank"] .

There is no "main" function, as it is automatically generated by boost (used in unit tests).

  • Please ensure that it contains sufficient tests cases to verify your code is OK (normal case, error cases).

Example here : // Case normal, with an existing image file.

remplacer ici par le nouveau code source SolAR 
BOOST_AUTO_TEST_CASE(TestLoadImage)
{ // To simplify this example test, let's suppose we'll test 'float'.
 // Some test are stupid, but all should pass.
 int result= 0;
 std::shared_ptr<IArgoImage> myArgoImage0 = getArgoImageInstance();

....
BOOST_CHECK( myArgoImage0 !=  NULL);
....

// getArgoImageInstance should not return a null pointer result

myArgoImage0->LoadImage("../test.jpg");
BOOST_TEST( result= = 0,"ARGO ERROR: Load Image should return 0");
// As the image indicated exists, loadImage should return 0, as a normal case

}

BOOST_AUTO_TEST_CASE(TestLoadImageInexistante)
{
// Some test are stupid, but all should pass.
int result= 0; std::shared_ptr<IArgoImage>
myArgoImage0 =  getArgoImageInstance();

....
BOOST_TEST(( myArgoImage0 !=  NULL),&quot;ARGO ERROR: ArgoImage should not return null pointer&quot;);

result=  myArgoImage0-&gt;LoadImage(&quot;../test2.jpg&quot;);
BOOST_TEST( result= = -1,&quot;ARGO ERROR: Load Image should return -1&quot;);
....

// As the image indicated does not exist, loadImage should return -1, an error

 }

Check your project unit tests

Run it with the command line here *>results.xml -x --log_format= XML -l all -o XML -m XML -r detailed

Unit test run

Execute your unit tests. A command prompt should display results.

  • Each test results is identified with its name

boost test results

Thanks to the ">results.xml" argument, a file should be created with the resulta of your tests. This are the results than jenkingswill use when your unit tests will be integrated in jenkins .

Add your unit tests in jenkins stream

Adding unit tests in jenkins stream requires to modify a shell script in the ArgoAll git repository. First, clone ArgoAll and switch to the develop branch:

git clone -b develop ssh://gitolite@forge.b-com.com/argo/F-Argo/ArgoAll.git

Then edit the file "newbuild.sh" inside the ArgoAll folder. Find the string "# BUILDING AND RUNNING UNIT TEST". You will see several lines looking like this:

makeAndInstall &quot;ArgoImageOpencv/unittest&quot; &quot;../../../../ArgoImageOpencv/unittest/ArgoImageOpencvUnitTest.pro&quot;

  • Now copy paste this line, and replace "ArgoImageOpencv/unittest" with "[Yourcomponent]/unittest" and "ArgoImageOpencvUnitTest.pro" by [YouComponentUnitTest.pro].

  • This new line will ensure that your test will be built by Jenkins.

  • Then find the string "running unit tests". You will see lines looking like this: ./ArgoImageOpencvUnitTest --log_format= JUNIT --log_level= all --report_level= no --log_sink= ../../../tests/ArgoImageOpencvUnitTest.xml

  • Copy paste this line, and replace : . "ArgoImageOpencvUnitTest" with [YouComponentUnitTest] . "ArgoImageOpencvUnitTest.xml" with[YouComponentUnitTest].xml

  • This new line will ensure that Jenkins will run your test. Save and close "newbuild.sh".

  • Commit and push your changes. Done!

Create your API documentation

:toclevels:2

NOT VALIDATED TIP: Write here if you validate with your name and your comment

See doxgen syntax, with the samples given by SolAR framework.

If you use QT creator, you can use the DOXYGEN comments completions (check if activated in options/completion)

DOC API for Estimation pose developper

If your documentation is destinated to Estimation Pose Developper or designer, aka framework users, you just need to comment your H files that are shared in SolAR framewok

remplacer ici par le GIT SolAR 
git clone ssh://gitolite@forge.b-com.com/argo/F-Argo/ArgoFramework.git

This is a subpart of documentation, as Framework users don’t need to know how the SolAR framework is built inside.

Comments for SolAR comunity

je pense que cette partie n’est pas claire, à reformuler You have to comment your whole code with the same format as the H files, with doxygen format. No Doxygen documentation will be generated, but the comments will help the SolAR comunity to understand and contribute to the code.

Generate API documentation with doxygen A REVOIR

cette partie est à revoir complètement, suite à l’intégration de la création de doc DOXYGEN dans jenkins. Download Doxygen http://www.stack.nl/~dimitri/doxygen/ Install it on your computer. You can use Doxygen in two modes. Run Doxygen :

You just have to run Doxygen on the "SolARFramework" project. It will generate API documentation based on H files in the SolAR framework repository. *The API documentation will be available in a directory named doxygen and subdirectory html.

Publish your doxgen documentation A REVOIR

cette partie est à revoir complètement, suite à l’intégration de la création de doc DOXYGEN dans jenkins. copy and paste your doxygen directory from the working directory with your clone of SolAR website. If not already done, execute:
remplacer ici par le GIT SolAR 
cd c:/DEV/websiteSolAR
git clone ssh://gitolite@forge.b-com.com/argo/Argo-Doc/argo-site.git solAR
git checkout develop

add your doxygen directory in git website directory example

remplacer ici par le GIT SolAR 
cp doxygen c:/DEV/solAR
cd c:/DEV/solAR
git status
git commit
git checkout
git push

Check your documentation is available

Consult this link to be sure the documentation is up-to-date.

changer le lien avec le nouveau lien
remplacer ici par le lien doc SolAR

https://forge.b-com.com/www/SolAR/doxygen/html/

Share your component to the SolAR community

NOT VALIDATED TIP: Write here if you validate with your name and your comment

Commit your component to the gforge

In your new SolARComponent folder

git init

Add an initial file for the first commit

git add README.adoc

First local commit

git commit -m "first commit : README.adoc"
est-ce encore d’actualité? on n’aura plus un GIT par composant,si ? Create the git repository on the gforge. For example, here the url of the ArgoDescriptor component

Push the first file to the distant repository

remplacer ici par le GIT SolAR 
git remote add origin http://forge.b-com.com/git/argo/F-Argo/packages/ArgoDescriptor.git
git push --set-upstream origin master

Move to the develop branch git branch develop

git push --set-upstream origin develop

Component manager overview

The component manager will help you to load and use your component.

Please have a look at the component manager to know how to create your component compliant with the framework.

Please click here to know more about XPCF, the component manager used in SolAR framework.

rajouter lien ici

Contact

Contact Mail

For any requests, please contact us.