Add documentation to debug with VS Code and CLion (possible solution to

#255)

Documentation/developers/debugging.rst

@@ -53,8 +53,8 @@ More information is available in the :ref:`debugging the polycubed daemon <polyc
 
 .. _logging-data-plane:
 
-Logging in the data plane
-*************************
+Logging the eBPF data plane
+***************************
 
 The common eBPF primitive ``bpf_trace_printk()``, which is widely used in other eBPF frameworks, should not be used in Polycube.
 Polycube offers a new ``pcn_log()`` primitive, which integrates both data and control plane logging in the same location.
@@ -103,8 +103,9 @@ Usage example:
 
 .. _logging-control-plane:
 
-Logging in the control plane
-****************************
+
+Logging the control plane
+*************************
 
 Custom ``printf()`` or similar primitives, which make the code difficult to debug, should not be used in the Polycube control plane.
 In fact, the ``pcn_log()`` primitive presented below can be used also in the control plane, as Polycube includes a powerful logging system implemented within a dedicated class.
@@ -116,3 +117,93 @@ Usage example:
   logger()->info("Connected port {0}", port_name);
   logger()->debug("Packet size: {0}", packet.size());
   
+
+
+Debugging using Integrated Development Environment (IDE)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+VS Code 
+***************
+
+Polycube uses ``cmake`` to create the compilation environment (Makefiles, etc), which, by default is configured to create the executables in ``Release`` mode.
+To debug your code, you must compile Polycube in ``Debug`` mode, with the following commands (follow also `here <https://stackoverflow.com/questions/7724569/debug-vs-release-in-cmake>`_):
+
+  :: 
+
+    mkdir Debug
+    cd Debug
+    cmake -DCMAKE_BUILD_TYPE=Debug ..
+    make -j
+
+Once all the Polycube executables have been created with _debug_ information, you must install them in the default folders with the following command:
+
+  ::
+
+    sudo make install
+
+Now, let's create a ``launch.json`` file, following the VS Code instructions:
+
+   1. Run
+   2. Start Debugging (or Add Configuration)
+   3. Select the C ++ template (GDB/LLDB)
+   4. Default configuration
+   5. As "program", add ``/usr/local/bin/polycubed``, which represents the default location. Alternatively, if you modified the installation script, enter the path that comes out as a result of the  ``which polycubed`` command
+   6. As "args", add ``["--loglevel=DEBUG"]`` to enable Polycube debug mode logging, which provides diagnostic information useful to people more than just developers. Note that the Polycube _debug_ logging (which simply means _the highlest level of verbosity_) is independent from the build type, hence it has to be enabled explicitly.
+   7. Later, also following this `link <https://stackoverflow.com/questions/40033311/how-to-debug-programs-with-sudo-in-vscode>`_, create a file called "gdb" in  "home/{username}" (for example) and enter ``pkexec /usr/bin/gdb "$@"`` to make sure that you are prompted to enter the password at startup. This is because Polycube requires root permissions to run. Finally just edit the ``launch.json`` file with these 3 lines:
+
+  ::
+
+      "externalConsole": false,
+      "miDebuggerPath": "/home/<username>/gdb",
+      "MIMode": "gdb",
+
+
+The final ``launch.json`` file should be something like the following:
+::
+
+    {
+        // Use IntelliSense to learn about possible attributes.
+        // Hover to view descriptions of existing attributes.
+        // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+        "version": "0.2.0",
+        "configurations": [
+            {
+                "name": "(gdb) Launch",
+                "type": "cppdbg",
+                "request": "launch",
+                "program": "/usr/local/bin/polycubed",
+                "args": ["--loglevel=DEBUG"],
+                "stopAtEntry": false,
+                "cwd": "${fileDirname}",
+                "environment": [],
+                "externalConsole": false,
+                "miDebuggerPath": "/home/pino/gdb",
+                "MIMode": "gdb",
+                "setupCommands": [
+                    {
+                        "description": "Abilita la riformattazione per gdb",
+                        "text": "-enable-pretty-printing",
+                        "ignoreFailures": true
+                    }
+                ]
+            }
+        ]
+    }
+
+
+
+CLion
+^^^^^^
+
+If you use CLion, you can debug Polycube with the following steps:
+
+1. Run CLion with sudo (Polycube needs root permissions)
+2. Set breakpoints and build/install Polycube (as explained above)
+3. At this point there are two equivalent ways to debug Polycube with CLion:
+
+   a. Use the CLion debugger: at the top right select Debug 'polycube';
+   b. (or) Run Polycube in a terminal like that ``sudo polycubed --loglevel = DEBUG`` in order to enable the Polycube Debug logs and then from CLion, go to Run->Attach to Process.. and search for "polycubed"
+
+4. At this point, from another terminal, just use ``polycubectl`` to interact with Polycube
+