Skip to content

Commit 6548f99

Browse files
kmohyeldinekmohyeldine
committed
docs: add Building libfranka Inside Docker and Vs code to README
1 parent 4dc2042 commit 6548f99

File tree

2 files changed

+207
-15
lines changed

2 files changed

+207
-15
lines changed

‎README.rst‎

Lines changed: 176 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,9 +57,181 @@ To use libfranka version ``0.14.0`` or later, you will need to install `pinocchi
5757
sudo apt-get update
5858
sudo apt-get install -y robotpkg-pinocchio
5959
60+
.. _building-in-docker:
61+
62+
3. Building libfranka Inside Docker
63+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64+
65+
If you prefer to build **libfranka** inside a Docker container, you can use the provided Docker setup. This ensures a consistent build environment and avoids dependency conflicts on your host system.
66+
67+
Docker creates a self-contained environment, which is helpful if:
68+
69+
- Your system doesn't meet the requirements
70+
- You want to avoid installing dependencies on your main system
71+
- You prefer a clean, reproducible setup
72+
73+
If you haven't already, clone the **libfranka** repository:
74+
75+
.. code-block:: bash
76+
77+
git clone --recurse-submodules https://github.com/frankarobotics/libfranka.git
78+
cd libfranka
79+
git checkout <desired-tag-or-branch>
80+
81+
Using Docker command line
82+
^^^^^^^^^^^^^^^^^^^^^^^^^
83+
84+
1. **Build the Docker image**:
85+
86+
.. code-block:: bash
87+
88+
cd .ci
89+
docker build -t libfranka:latest -f Dockerfile.focal .
90+
cd ..
91+
92+
2. **Run the Docker container**:
93+
94+
.. code-block:: bash
95+
96+
docker run --rm -it -v $(pwd):/workspace libfranka:latest
97+
98+
If you already have a build folder, you must remove it first to avoid issues:
99+
100+
.. code-block:: bash
101+
102+
rm -rf /workspace/build
103+
mkdir -p /workspace/build
104+
cd /workspace/build
105+
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=OFF /workspace
106+
make
107+
108+
To generate a Debian package:
109+
110+
.. code-block:: bash
111+
112+
sudo cpack -G DEB
113+
114+
Exit the Docker container by typing ``exit`` in the terminal.
115+
116+
3. **Install libfranka on your host system**:
117+
118+
Inside the libfranka build folder ``cd build`` on your host system, run:
119+
120+
.. code-block:: bash
121+
122+
sudo dpkg -i libfranka*.deb
123+
124+
125+
Using Visual Studio Code
126+
^^^^^^^^^^^^^^^^^^^^^^^^
127+
128+
You can also build **libfranka** inside Docker using **VS Code** with the **Dev Containers** extension. This provides an integrated development environment inside the container.
129+
130+
1. **Install Visual Studio Code**:
131+
132+
- Download and install **Visual Studio Code** from the official website: https://code.visualstudio.com/.
133+
- Follow the installation instructions for your operating system.
134+
135+
2. **Open the Project in VS Code**:
136+
137+
Inside the libfranka folder, open a new terminal and run:
138+
139+
.. code-block:: bash
140+
141+
code .
142+
143+
This will open the project in VS Code.
144+
145+
3. **Install the Dev Containers Extension**:
146+
147+
Install the "Dev Containers" extension in VS Code from the Extensions Marketplace.
148+
149+
4. **Open the Project in a Dev Container**:
150+
151+
- Open the **Command Palette** (``Ctrl+Shift+P``).
152+
- Select **Dev Containers: Reopen in Container**.
153+
- VS Code will build the Docker image and start a container based on the provided ``.ci/Dockerfile``.
154+
155+
5. **Build libfranka**:
156+
157+
- Open a terminal in VS Code.
158+
- Run the following commands:
159+
160+
.. code-block:: bash
161+
162+
mkdir build && cd build
163+
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=OFF ..
164+
make
165+
166+
6. **Install libfranka**:
167+
168+
If you want to install **libfranka** inside the container, you can run:
169+
170+
.. code-block:: bash
171+
172+
sudo make install
173+
174+
If you want to install **libfranka** on your host system, you can run:
175+
176+
.. code-block:: bash
177+
178+
sudo cpack -G DEB
179+
180+
Then in a new terminal on your host system, navigate to the libfranka ``build`` folder and run:
181+
182+
.. code-block:: bash
183+
184+
sudo dpkg -i libfranka*.deb
185+
186+
.. _verifying-installation:
187+
Verify the installation on your local system
188+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
189+
190+
To verify its installation, you can run:
191+
192+
.. code-block:: bash
193+
194+
ls /usr/lib/libfranka.so
195+
196+
Expected output:
197+
198+
.. code-block:: text
199+
200+
/usr/lib/libfranka.so
201+
202+
Check the installed headers:
203+
204+
.. code-block:: bash
205+
206+
ls /usr/include/franka/
207+
208+
Expected output:
209+
210+
.. code-block:: text
211+
212+
active_control_base.h active_torque_control.h control_tools.h errors.h
213+
gripper_state.h lowpass_filter.h robot.h robot_state.h
214+
active_control.h async_control control_types.h exception.h
215+
joint_velocity_limits.h model.h robot_model_base.h vacuum_gripper.h
216+
active_motion_generator.h commands duration.h gripper.h
217+
logging rate_limiting.h robot_model.h vacuum_gripper_state.h
218+
219+
You can check the version of the installed library:
220+
221+
.. code-block:: bash
222+
223+
dpkg -l | grep libfranka
224+
225+
Expected output:
226+
227+
.. code-block:: text
228+
229+
ii libfranka 0.18.1-9-g722bf63 amd64 libfranka built using CMake
230+
231+
60232
.. _building-from-source:
61233

62-
3. Building and Installation from Source
234+
4. Building and Installation from Source
63235
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64236

65237
Before building and installing from source, please uninstall existing installations of libfranka to avoid conflicts:
@@ -131,7 +303,7 @@ Installing via a Debian package simplifies the process compared to building from
131303

132304
.. _usage:
133305

134-
4. Usage
306+
5. Usage
135307
~~~~~~~~
136308

137309
After installation, check the `Minimum System and Network Requirements <https://frankarobotics.github.io/docs/requirements.html>`_ for network settings, the `Operating System and PC Configuration <https://frankarobotics.github.io/docs/installation_linux.html#setting-up-the-real-time-kernel>`_ for system setup, and the `Getting Started Manual <https://frankarobotics.github.io/docs/getting_started.html#>`_ for initial steps. Once configured, you can control the robot using the example applications provided in the examples folder.
@@ -144,14 +316,14 @@ To run a sample program, navigate to the build folder and execute the following
144316
145317
.. _pylibfranka:
146318

147-
5. Pylibfranka
319+
6. Pylibfranka
148320
~~~~~~~~~~~~~~
149321

150322
Pylibfranka is a Python binding for libfranka, allowing you to control Franka robots using Python. It is included in the libfranka repository and can be built alongside libfranka. For more details, see ``pylibfranka`` and its `README <pylibfranka/README.md>`_. The `generated API documentation <https://frankarobotics.github.io/libfranka/pylibfranka/latest>`_ offers an overview of its capabilities.
151323

152324
.. _development-information:
153325

154-
6. Development Information
326+
7. Development Information
155327
~~~~~~~~~~~~~~~~~~~~~~~~~~
156328

157329
If you actively contribute to this repository, you should install and set up pre-commit hooks:

‎docs/installation.rst‎

Lines changed: 31 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,31 +3,51 @@
33
Build / Installation
44
--------------------
55

6-
.. _libfranka_installation_plain_cmake:
7-
Plain CMake
8-
~~~~~~~~~~~
9-
10-
Before you begin, check the :ref:`system-requirements` and install the necessary dependencies listed in :ref:`installing-dependencies`.
11-
12-
After installing the dependencies, proceed to :ref:`building-from-source`.
13-
14-
Once the build is complete, you can optionally create and install a Debian package as described in :ref:`installing-debian-package`.
15-
166
.. _libfranka_installation_debian_package:
177
Debian Package
188
~~~~~~~~~~~~~~
199

2010
Starting with version 0.18.1, **libfranka** releases are provided as pre-built Debian packages.
2111
You can find the packaged artifacts on the `libfranka releases <https://github.com/frankarobotics/libfranka/releases/>`_ page on GitHub.
2212

23-
To install the Debian package directly on your system, run:
13+
Download the Debian package:
2414

2515
.. code-block:: bash
2616
17+
wget https://github.com/frankarobotics/libfranka/releases/download/0.18.1/libfranka_0.18.1_amd64.deb
18+
19+
Install the package on your system:
20+
21+
.. code-block:: bash
22+
23+
sudo dpkg -i libfranka_0.18.1_amd64.deb
24+
25+
For other versions or architectures, use the following pattern:
26+
27+
.. code-block:: bash
28+
29+
wget https://github.com/frankarobotics/libfranka/releases/download/<version>/libfranka_<version>_<architecture>.deb
2730
sudo dpkg -i libfranka_<version>_<architecture>.deb
2831
2932
This is the recommended installation method for **libfranka** if you do not need to modify the source code.
3033

34+
.. _libfranka_installation_docker:
35+
Inside docker container
36+
~~~~~~~~~~~~~~~~~~~~~~~
37+
If you prefer to build **libfranka** inside a Docker container, you can use the
38+
provided Docker setup. Follow :ref:`building-in-docker` for detailed building
39+
and installation instructions.
40+
41+
.. _libfranka_installation_plain_cmake:
42+
Plain CMake
43+
~~~~~~~~~~~
44+
45+
Before you begin, check the :ref:`system-requirements` and install the necessary dependencies listed in :ref:`installing-dependencies`.
46+
47+
After installing the dependencies, proceed to :ref:`building-from-source`.
48+
49+
Once the build is complete, you can optionally create and install a Debian package as described in :ref:`installing-debian-package`.
50+
3151
.. _libfranka_installation_pip:
3252
Python Package (pip)
3353
~~~~~~~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)