Re: [cmake-developers] cmake --help-custom-modules compatibility
On Wednesday 08 January 2014, you wrote: On 11/20/2013 07:22 PM, Stephen Kelly wrote: The solution is still to re-implement the --help-custom-modules myman.1 command-line behavior as a special case with warnings. Alex and Steve will have to work out who takes responsibility for that. I'll defer to Alex on doing that I think. Alex, Steve, we need to resolve this compatibility issue soon in preparation for the 3.0 release. since a few weeks I only sporadically find some time :-), so don't rely on me, I can't promise anything currently. Alex -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] cmake --help-custom-modules compatibility
Brad King wrote: If you want CMake 3.0 to do anything better than this then please work on the minimal re-implementation ASAP. Much of the logic can be extracted from old versions and refactored into an isolated compatibility implementation. I think this suffices for now. I'm not aware of any packagers who will try to package old kde releases with new cmake. Let's see if anyone complains. Thanks, Steve. -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] cmake --help-custom-modules compatibility
On 11/20/2013 07:22 PM, Stephen Kelly wrote: The solution is still to re-implement the --help-custom-modules myman.1 command-line behavior as a special case with warnings. Alex and Steve will have to work out who takes responsibility for that. I'll defer to Alex on doing that I think. Alex, Steve, we need to resolve this compatibility issue soon in preparation for the 3.0 release. IIUC this KDE change: Only create and install man pages if using CMake 3.0 http://quickgit.kde.org/?p=kdelibs.gita=commitdiffh=804d3539 was needed to avoid breaking the build when --help-custom-modules does not generate the manual page. This means existing KDE releases will not build successfully without this patch. In order to more gracefully degrade behavior I've made this change: cmake: Implement placeholder --help-custom-modules compatibility http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=b1772946 Now it generates the requested file without error but the content is just a placeholder explaining that the functionality was dropped. It still produces a warning of course. If you want CMake 3.0 to do anything better than this then please work on the minimal re-implementation ASAP. Much of the logic can be extracted from old versions and refactored into an isolated compatibility implementation. Thanks, -Brad -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] cmake --help-custom-modules compatibility
On 2014-01-08 11:26, Brad King wrote: On 11/20/2013 07:22 PM, Stephen Kelly wrote: The solution is still to re-implement the --help-custom-modules myman.1 command-line behavior as a special case with warnings. Alex and Steve will have to work out who takes responsibility for that. In order to more gracefully degrade behavior I've made this change: cmake: Implement placeholder --help-custom-modules compatibility http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=b1772946 Now it generates the requested file without error but the content is just a placeholder explaining that the functionality was dropped. It still produces a warning of course. Since you mentioned it, I was wondering if this is related to a feature I was asking about, but I don't understand how it works; it seems to only ever generate a short boilerplate text. Is this meant to take a CMake module that is not part of the CMake distribution and extract and format the documentation from the same? Because that is a feature I really wish CMake 3.0 would provide. (I know you (Brad) previously mentioned that you don't want to in order to avoid committing to any sort of compatibility guarantees with respect to the same. But it still seems to me that such decision makes it unnecessarily hard for third parties to provide documented CMake modules.) -- Matthew -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] cmake --help-custom-modules compatibility
On 01/08/2014 12:00 PM, Matthew Woehlke wrote: Since you mentioned it, I was wondering if this is related to a feature I was asking about, but I don't understand how it works; it seems to only ever generate a short boilerplate text. Is this meant to take a CMake module that is not part of the CMake distribution and extract and format the documentation from the same? The old documentation system exposed this feature through the old --help-custom-modules option. The new documentation system does not. This commit is about making old builds not totally break. Because that is a feature I really wish CMake 3.0 would provide. (I know you (Brad) previously mentioned that you don't want to in order to avoid committing to any sort of compatibility guarantees with respect to the same. But it still seems to me that such decision makes it unnecessarily hard for third parties to provide documented CMake modules.) That discussion left off here: http://thread.gmane.org/gmane.comp.programming.tools.cmake.devel/8727/focus=8943 and should continue there rather than here. In summary I pointed out that there is no clean way to cross-reference CMake's documentation from external modules except by spelling out hyperlinks by hand. I also suggested an approach to document external modules without using CMake's Sphinx configuration. Anyone could fork CMake's Utilities/Sphinx infrastructure and provide it as a separate distribution with support and compatibility guarantees. I just do not want to provide it with CMake and constrain CMake's own documentation from evolving just to support external documents. The compatibility issue in this thread is a perfect example of why. -Brad -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] cmake --help-custom-modules compatibility
On 2014-01-08 12:57, Brad King wrote: On 01/08/2014 12:00 PM, Matthew Woehlke wrote: Since you mentioned it, I was wondering if this is related to a feature I was asking about, but I don't understand how it works; it seems to only ever generate a short boilerplate text. Is this meant to take a CMake module that is not part of the CMake distribution and extract and format the documentation from the same? The old documentation system exposed this feature through the old --help-custom-modules option. The new documentation system does not. This commit is about making old builds not totally break. Because that is a feature I really wish CMake 3.0 would provide. (I know you (Brad) previously mentioned that you don't want to in order to avoid committing to any sort of compatibility guarantees with respect to the same. But it still seems to me that such decision makes it unnecessarily hard for third parties to provide documented CMake modules.) Anyone could fork CMake's Utilities/Sphinx infrastructure and provide it as a separate distribution with support and compatibility guarantees. I just do not want to provide it with CMake and constrain CMake's own documentation from evolving just to support external documents. The compatibility issue in this thread is a perfect example of why. From my perspective, that's sort-of the point here... CMake used to provide for generating documentation from external modules. Now it doesn't. And it seems that KDE is also feeling that pain. I'm not convinced that's a good thing. I get that you don't want to make things harder for developers, but doing so at the expense of making things harder for users doesn't seem like the best trade-off. I'm also not sure I'm convinced by the compatibility argument. If you can't guarantee compatibility, then don't. Projects that want to use CMake to generate documentation for their CMake modules simply must use the version of CMake their documentation was written for to do so. (And update as necessary to meet the previous condition. Or fork the documentation system anyway.) -- Matthew -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] cmake --help-custom-modules compatibility
On 01/08/2014 01:32 PM, Matthew Woehlke wrote: From my perspective, that's sort-of the point here... CMake used to provide for generating documentation from external modules. Now it doesn't. And it seems that KDE is also feeling that pain. That is the issue that started this thread. I've invited re-implementation of the original --help-custom-modules functionality with minimal and isolated restoration of the old code but no one has stepped forward to do it. This would allow external modules using the old simple markup syntax to be documented again. It was just a simple text transformation supporting only prose paragraphs and pre-formatted blocks. -Brad -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] cmake --help-custom-modules compatibility
Brad King wrote: On 11/18/2013 04:34 PM, Alexander Neundorf wrote: the author of the --help-custom-modules command line option certainly intended this to be used by other projects. ;-) I don't know whether this is used only in KDE or also in other projects. The solution is still to re-implement the --help-custom-modules myman.1 command-line behavior as a special case with warnings. Alex and Steve will have to work out who takes responsibility for that. I'll defer to Alex on doing that I think. As an unrelated matter, I would like to find out whether any packages in, eg debian fail to build with CMake 3. I'll try to figure out a way to find out. --unknownUnknowns; Thanks, Steve. -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
Re: [cmake-developers] cmake --help-custom-modules compatibility (was: RST and documentation)
On Monday 18 November 2013, Brad King wrote: On 11/18/2013 02:56 PM, Stephen Kelly wrote: We've had a while now to get used to the new docs system. Mostly I like it, though I haven't really looked much into what rst offers. This is really the start of several threads so I will branch out now. 2) Compatibility KDE relied on --help-custom-modules for creating a man page of the kde cmake modules. That does not work with CMake 3.0.0: http://quickgit.kde.org/?p=kdelibs.gita=commitdiffh=804d35394c366 I am left wondering why it would be difficult to process the existing (and very simple) markup in custom modules and generate rst on the fly for output from --help-module MyCustomModule and similar. Is there a reason not to restore compatibility like that? Otherwise any distro which upgrades to cmake 3 will lose those man pages in the KDE case, and probably similar in other cases. I think it would be best to avoid situations like distros packaging cmake 2.8 and cmake 3.0, possibly renaming executables etc etc so that KDE4 and other packages can continue to rely on cmake 2.8. Restoring and keeping compatibility with issues like this would be important to prevent that. The conversion topic was massive as it was and I didn't want to handle this. I didn't know it was used for anything except local command-line help convenience. The old help infrastructure was certainly not ever intended for invocation in project build rules. the author of the --help-custom-modules command line option certainly intended this to be used by other projects. ;-) I don't know whether this is used only in KDE or also in other projects. Alex -- Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Please keep messages on-topic and check the CMake FAQ at: http://www.cmake.org/Wiki/CMake_FAQ Follow this link to subscribe/unsubscribe: http://public.kitware.com/cgi-bin/mailman/listinfo/cmake-developers
