[kamailio/kamailio] cmake - make clean deletes readme files from modules source folders (Issue #4084)
Executing `make clean` in the `build` folder deletes the `README` files from the modules folders.
This is probably because the README is an output of a `cmake-make` command. What would be the best option to skip this removing?
I found:
- https://stackoverflow.com/questions/6259372/cmake-preventing-make-clean-from...
Which indicates adding:
``` SET_DIRECTORY_PROPERTIES(PROPERTIES CLEAN_NO_CUSTOM 1) ```
In the CMakeLists.txt inside the module folders. But maybe it is another place where it can be done once for all modules, or another option...
@miconda
Does this happen after you have build the `kamailio_docs` target? Doing `make all` and then `make clean` does not clean the README as far as I can see, only if `make kamailio_docs` was previously run. We still don't want that, just want to have this observation noted.
Reading the docs for `CLEAN_NO_CUSTOM`, it seems to work as you want, but it is only available for `Makefiles`.
I would propose, to not break this functionality if one wants to use some other build tool and instead modify the `custom command` to
``` add_custom_command( OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${MODULE_NAME}/README # Copy the README file to the build directory so that `clean` target will clean the # README file found in build folder. but stiil keep the README file in the # source folder. COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_BINARY_DIR}/${MODULE_NAME}/${MODULE_NAME}.txt ${CMAKE_CURRENT_BINARY_DIR}/${MODULE_NAME}/README COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_BINARY_DIR}/${MODULE_NAME}/${MODULE_NAME}.txt ${CMAKE_CURRENT_SOURCE_DIR}/${MODULE_NAME}/README DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${MODULE_NAME}/${MODULE_NAME}.txt COMMENT "Generating README file for module ${MODULE_NAME}") ```
This would first build the readme doc target, copying the `.txt` into `README` in the build folder, since best practices of cmake expect all generated files to be in the build folder and have that as the output file. Then just also copy to each module's folder and since it's not the output anymore, clean won't do anything to.
Also, the expected behavior of clean is to clean everything, so it makes sense I think to have rebuild the docs fresh!
Fine for me whatever is considered better.
For the records, I saw that there could be target events, like POST_BUILD, but I am not sure if it can be useful here:
- https://cmake.org/cmake/help/latest/command/add_custom_command.html#build-ev...
The readme generation has to be standalone, it must not generate the other doc formats. It is used on server to generate the readme (then push to git) after a developer pushes changes to module's xml doc files.
Hey @miconda I pushed c8544e48710fa74150b958a1f8d1e918973afb51. After this commit, it should not clean the README from the source tree.
Can you confirm?
Also, I have added `module_name_readme` target to `module_name_doc` target as a dependency, so when one calls `module_name_doc` all of the forms are generated, like the .txt and .HTML in the build folder and README in source tree.
The readme generation has to be standalone, it must not generate the other doc formats. It is used on server to generate the readme (then push to git) after a developer pushes changes to module's xml doc files.
As for this, README is just the `doc_text` but copied to another place, `README` will produce this target but not the HTML. We can combine these two targets, if we want only one text format I guess.
`make clean` leaves now the readmes in place in the source tree.
Also, I have added `module_name_readme` target to `module_name_doc` target as a dependency, so when one calls `module_name_doc` all of the forms are generated, like the .txt and .HTML in the build folder and README in source tree.
This should not be done, the readme is generated as part of the development process, not at compile/install time. The readmes are in the source tree as a documentation for the modules (some of them, although only a few, have also devel-related sections -- should have been more, but nobody got time to focus on documenting inter-module apis).
In other words, the building of the generation has to be done only on demand, for the format that is desired (eg, html, text, pdf, ... or all of them), but not the modules' READMEs, which are actually the text format, but named README in each module folder.
Hey @miconda,
After commit 2692148d92bb8b17709eb4cbddd8e653bbf5c14a, the `readme` target should be called explicitly, to produce and overwrite the source tree READMEs. It's also not called when one uses the target `module_name_doc`, this now builds the HTML and txt formats in the build directory, again if target is called explicitly.
Is this what you expect from the readme?
@henningw @miconda
Regarding the `BUILD_DOC` option and doc generation (not including the README in source tree).
I introduced this when first prototyping CMake support and it's initial usage was to provide the doc targets if set to YES. Seems wrong.
After some discussion with @henningw, I implemented 18705086c2dbeef21afc059c887ab2c6178deba9, so that docs targets are always there.
Now, I see no extra usage of `BUILD_DOC` since the docs are never generated in the default target. They need explicit calls.
If we want, we can build the documentation as well in the default target if it is set to ON, or not if OFF. Otherwise, there is no need for the option, and I am considering removing it.
What are your thoughts?
Now the make clean executed in the build folder don't delete the READMEs from the source folder anymore.
``` ~/repositories/kamailio$ cmake --build build/ [..] ~/repositories/kamailio$ cd build/ ~/repositories/kamailio/build$ make clean ~/repositories/kamailio/build$ cd .. ~/repositories/kamailio$ find . -name "README" ./utils/kamctl/README ./utils/kamctl/oracle/admin/README [..] ```
This issue could be probably closed then, if there are no other related topics.
Closed #4084 as completed.
-
Daniel-Constantin Mierla -
Henning Westerholt
-
Xenofon Karamanos