ROS2_pubsub/non-ros-files/Programming_Rules.md

# Rules for programming with Python in ROS2
## File Structure
```
colcon_workspace  
      |  
      |- build     (holds build files)
      |- install   (holds build elements)
      |- src       (contains your source code - this is where you work)
```

## Colcon Build
Performing a `colcon build` is neccessary after every change to the `src` directory. This must be performed in the `root` of the _colcon_ workspace (eg. `cd ~/colcon_ws`).

In order to avoid this procedure after every change made to a Python script you must run `colcon build --symlink-install` once. This links the files created in `/build` and `/install` to your source files in `/src`. However, after creating a new Python script this procedure must be repeated in order to also link this new script.

## Source Directory
The source directory holds your ROS2 packages in the form of directories. In this example the `src` directory contains the exemplary packages `pubsub` and `pubsub_msg`:
```
colcon_workspace/
      |
      |- src/
          |
          |- pubsub/
          |- pubsub_msg/
```
The `src` directory is also the place where you create your new packages using `ros2 pkg create ...` and not in the root of the workspace.  

The next chapters will describe the content of the files inside a package directory. However, the occuring files depend on the type of package (`ament_cmake` for C++ scripts or `ament_python` for Python scripts). This is described in detail [here](https://docs.ros.org/en/foxy/Tutorials/Creating-Your-First-ROS2-Package.html). The following chapters only describe Python packages (eg. `pubsub/`).


## setup.py
The file _setup.py_ is used to create entry points, meaning you link your python scripts to names which you can be called through `ros2 run ...`. In order for this to work your python scripts must be written using the following mechanism
```python
def main():
  # main code

if __name__ == "__main__":
  main()
```
in which you put all of your code inside `main()`. This prevents any code from being run, if this script is not run as main.  

Linking your scripts to names is done inside the file _setup.py_ by defining entry points:
```python
entry_points={
   'console_scripts': [
       'talker = pubsub.talker:main',
       'listener = pubsub.listener:main'
   ],
},
```
The _setup.py_-excerp above links the the function `main()` from the scripts _talker.py_ and _listener.py_ from inside `/pubsub` to the names _talker_ and _listener_. This way they can be called using `ros2 run pubsub talker` or `ros2 run pubsub listener`.  
  
From this you can see that you need to follow the Python programming style of creating a _main()_ procedure, in order for the entry points to work.

## package.xml
The file _package.xml_ is used to link dependencies to this package. For example, if this package requires a _*.msg_ file which is located inside a different package this is defined in _package.xml_, eg.  
```
                  colcon_workspace
                          |
  ---------------------------------------------------
  |                                                 |
pubsub    <---- depends on *.msg files ----<    pubsub_msg
```

This is also done in the background when creating a new package and defining dependencies    
`ros2 pkg create <pkg-name> --dependencies [deps]`  
for example  
`ros2 pkg create pubsub_2 --dependencies std_msgs builtin_interfaces --build-type ament_cmake`  
This command creates the new package `pubsub_2` but already links it to the ROS standard messages `std_msgs` so they are available.

## pubsub/
The example package `pubsub/` contains a directory of the same name as the package. This is where you place your Python scripts. Inside this directory you are free to do as you please, however keep in mind that you need to link your main script (eg. `listener.py`) to a name later on (using _setup.py_).