catkin_make unable to create executable & automatically copy .h files to devel

edit

First: this is not a ROS problem per se, but really a matter of using CMake correctly.

I understand that it should automatically copy the header files [..] which I included in the main cpp file into devel/include

No, that is not the case: header files will not be copied to the devel space by catkin (unless they are auto-generated, or there are statements in the CMakeLists.txt that do that). It's also not necessary: the dependents include path will automatically include the correct paths (in the src space) if the providing package properly exports those include locations.

Error:

Linking CXX executable /home/catkin_ws/devel/lib/mqtt_pub/mqtt_pub_node
/usr/bin/ld: cannot find -lmosquitto.h
collect2: error: ld returned 1 exit status
[..]

Note that mqtt_pub_node doesn't exist. Why is it looking for something that doesn't exist? It should be automatically created.

yes, it should, but only if linking actually succeeded. Which it didn't.

From what I know, the executable should be in devel/lib/mqtt_pub, not sure where did the system think about devel/lib/mqtt_pub/mqtt_pub_node [..].

the error message you refer to simply states that while linking a binary called mqtt_pub_node (which will be placed in devel/lib/mqtt_pub if linking is successful), no library called mosquitto.h could be found. In your CMakeLists.txt, you defined the name of the binary as mqtt_pub_node with the add_executable(mqtt_pub_node ..) line.

catkin_package(
INCLUDE_DIRS include
LIBRARIES mqtt_pub
CATKIN_DEPENDS roscpp std_msgs
DEPENDS system_lib
)

include_directories(
  ${catkin_INCLUDE_DIRS}
  /catkin_ws/src/mqtt_pub/include/mqtt_pub
  include
)

link_directories(
  /catkin_ws/src/mqtt_pub/include/mqtt_pub
)

link_libraries(
mosquitto.h
)

add_executable(mqtt_pub_node src/mqtt_publish.cpp)
target_link_libraries(mqtt_pub_node ${catkin_LIBRARIES})

Multiple things are not as they should be here:

1. mosquitto.h is not a library (obviously), it's a header. In your CMakeLists.txt you are asking CMake to link_libraries(..) against that header. That will obviously not work, resulting in the error that you are seeing. Note that this will never work, not even if search paths were setup correctly

2. location of your workspace is slghtly unorthodox (directly under /home). That is definitely legal, but perhaps placing it in your user's home directory (ie: /home/$USER) would be better

3. I doubt your catkin workspace is located at /catkin_ws, as that would be in the root of your file system. From the error messages, it should be at least /home/catkin_ws, but see my previous comment

4. it's typically recommended to place your package's include directories before anything else, as that allows you to provide files that override system includes

5. the use of link_directories(..) is typically not recommended with CMake. Prefer to use absolute paths to libraries, as that will avoid surprises if anyone ever overrides your linker's search path

6. your catkin_package(..) invocation states that your package depends on something called system_lib. That is probably not correct

7. in the same catkin_package(..) invocation a LIBRARY called mqtt_pub is exported, but that library is not build by your CMakeLists.txt (or at least, not in the snippet that you included)

8. nowhere ...