Porting to CMake

[Alexey Kutumov]

Hi all!

I started to port boost build to CMake, here is repo: https://github.com/prograholic/boost-zero

I added support for auto-linking (under win32), started to migrate documentation to CMake - partially finished algorithm and array libraires, started to migrate asio.

Am i on the right way?

[Alexey Kutumov]

According to https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted i created following commands (i assume that name of command describe it behavior):

xslt_doxy_to_boostbook

quickbook_to_boostbook

xslt_boostbook_to_docbook

xslt_docbook_to_html

Using this commands i partially adopted generation of documentation for following libraries:

algorithm

algorithm/string

any

array

asio

I have not implemented yet generation of full documentation (for now CMake generates only standalone documentations), also generated html have some issues: missing css, images, samples of code.

среда, 9 января 2013 г., 0:37:46 UTC+7 пользователь Alexey Kutumov написал:

[Daniel Pfeifer]

Hey Alexey and welcome to the crew!
It seems like I cannot access your clones of the boost libraries on
bitbucket, but I like what I have seen on github.

Concerning the many different repositories and organizations I will
write a separate mail.
Once we decided where to CMake-ification takes place, you will get
direct write access there.

cheers, Daniel 

[Daniel Pfeifer]

Am Donnerstag, 10. Januar 2013 13:30:19 UTC+1 schrieb Alexey Kutumov:

According to https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted i created following commands (i assume that name of command describe it behavior):

xslt_doxy_to_boostbook

quickbook_to_boostbook

xslt_boostbook_to_docbook

xslt_docbook_to_html

Using this commands i partially adopted generation of documentation for following libraries:

algorithm

algorithm/string

any

array

asio

Nice, I saw that you also included documentation for these functions.

Did you know that CMake is able to generate its own documentation
(including custom CMake Modules!), in docbook format? To allow CMake
to extract the documentation from Ryppl's CMake Modules, they should
be commented in the CMake way. That means: The documentation should be
placed at the top of the file, above the copyright. The copyright
should be introduced with "#====...".

The DocBook then can be generated, and processed further using Boost's
stylesheets.

set(cmake_dbk "${CMAKE_CURRENT_BINARY_DIR}/cmake.docbook")
add_custom_command(OUTPUT ${cmake_dbk}
  COMMAND ${CMAKE_COMMAND}
    -DCMAKE_MODULE_PATH="${CMAKE_MODULE_PATH}"

    --help-full ${cmake_dbk}

  )

[Alexey Kutumov]

Hello Daniel, thanks for responce.

Bitbucket has very strange repo access management: when i fork repo i can give admin access to repo, or forbid access at all. Now i added team `ryppl` to all my forked repositiories, you may try to clone.

There is else one issue: some original repositories configured with "no public forks", so my fork actuallty private, only me, and team ryppl have access.

2013/1/11 Daniel Pfeifer <purple...@gmail.com>

[Mathias Gaunard]

On 11/01/2013 14:24, Alexey Kutumov wrote:
> Hello Daniel, thanks for responce.
>
> Bitbucket has very strange repo access management: when i fork repo i
> can give admin access to repo, or forbid access at all. Now i added team
> `ryppl` to all my forked repositiories, you may try to clone.
>
> There is else one issue: some original repositories configured with "no
> public forks", so my fork actuallty private, only me, and team ryppl
> have access.

I'm not part of the ryppl team, but I have personally wrote custom CMake
modules to generate documentation using the Boostbook toolchain, so I'd
be quite interested in being able to read your code.

[Alexey Kutumov]

As far as i understand, there is different settings in repositories.

For example https://bitbucket.org/ryppl/coroutine allows public fork, however https://bitbucket.org/ryppl/conversion does not allow public fork. I also can't change settings for original repositories.

I created group boost_cmake, and added readonly access to all my forked repositories. Also i added Mathias to this group

2013/1/11 Mathias Gaunard <louf...@gmail.com>

[Mathias Gaunard]

On 10/01/2013 13:30, Alexey Kutumov wrote:
> According to
> https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted i created
> following commands (i assume that name of command describe it behavior):
> xslt_doxy_to_boostbook
> quickbook_to_boostbook
> xslt_boostbook_to_docbook
> xslt_docbook_to_html

I just looked at quickbook_to_boostbook, and I can see a few problems
with it.
- If a file included by the quickbook file you're compiling is
modified, it won't get recompiled.
- Quickbook does weird things with paths relative to images and CSS,
and the only way to fix that is AFAIK to move the main input file to the
output directory.

For modular documentation generation, I have personally found it nice to
have a CMake function that flattens XIncludes in Boostbook, so that when
aggregating modules, documentation of a module is fully in a single file
without relative paths in it.
You guys may want to have that at some point as well.

[Daniel Pfeifer]

2013/1/11 Mathias Gaunard <louf...@gmail.com>:

> On 10/01/2013 13:30, Alexey Kutumov wrote:
>>
>> According to
>> https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted i created
>> following commands (i assume that name of command describe it behavior):
>> xslt_doxy_to_boostbook
>> quickbook_to_boostbook
>> xslt_boostbook_to_docbook
>> xslt_docbook_to_html
>
>
> I just looked at quickbook_to_boostbook, and I can see a few problems with
> it.
> - If a file included by the quickbook file you're compiling is modified, it
> won't get recompiled.
> - Quickbook does weird things with paths relative to images and CSS, and
> the only way to fix that is AFAIK to move the main input file to the output
> directory.

Yes, I made the same experience. I would call this a bug in quickbook.
It is wrong to assume that paths should be realtive to the input in
the output.

> For modular documentation generation, I have personally found it nice to
> have a CMake function that flattens XIncludes in Boostbook, so that when
> aggregating modules, documentation of a module is fully in a single file
> without relative paths in it.
> You guys may want to have that at some point as well.

In Boostbook? XIncludes get flattened when converting Boostbook to
DocBook. So we have one DocBook file per module.

[Mathias Gaunard]

On 11/01/13 15:41, Daniel Pfeifer wrote:

> In Boostbook? XIncludes get flattened when converting Boostbook to
> DocBook. So we have one DocBook file per module.

Yes, and that is in my opnion a limitation.
This prevents documentation to be split across several modules or even
to reference another module, since each boostbook is compiled to docbook
in isolation.

What I personally do is that I generate a single Boostbook with
processed XIncludes for each module, then I convert the whole bunch to
Docbook in one go.

[Dave Abrahams]

on Fri Jan 11 2013, Mathias Gaunard <loufoque-AT-gmail.com> wrote:

> On 11/01/2013 14:24, Alexey Kutumov wrote:
>> Hello Daniel, thanks for responce.
>>
>> Bitbucket has very strange repo access management: when i fork repo i
>> can give admin access to repo, or forbid access at all. Now i added team
>> `ryppl` to all my forked repositiories, you may try to clone.
>>
>> There is else one issue: some original repositories configured with "no
>> public forks", so my fork actuallty private, only me, and team ryppl
>> have access.
>
> I'm not part of the ryppl team,

Would you like to be?

--
Dave Abrahams
BoostPro Computing Software Development Training
http://www.boostpro.com Clang/LLVM/EDG Compilers C++ Boost

[Mathias Gaunard]

On 11/01/13 16:44, Dave Abrahams wrote:
>
> on Fri Jan 11 2013, Mathias Gaunard <loufoque-AT-gmail.com> wrote:
>
>> On 11/01/2013 14:24, Alexey Kutumov wrote:
>>> Hello Daniel, thanks for responce.
>>>
>>> Bitbucket has very strange repo access management: when i fork repo i
>>> can give admin access to repo, or forbid access at all. Now i added team
>>> `ryppl` to all my forked repositiories, you may try to clone.
>>>
>>> There is else one issue: some original repositories configured with "no
>>> public forks", so my fork actuallty private, only me, and team ryppl
>>> have access.
>>
>> I'm not part of the ryppl team,
>
> Would you like to be?
>

What does that imply?

[Alexey Kutumov]

I think that we can use both approaches, first one for generating per-library (standalone) documentation, and the second one for generating full documentation

2013/1/11 Mathias Gaunard <louf...@gmail.com>

[Dave Abrahams]

Basically, you'd get developer-level access to all the ryppl and boost repos. Now that Daniel has blessed alexy's work we should do the same for him.

Sent from my Q-42 Space Modulator

[Alexey Kutumov]

Mathias, can you show me sample of your code which merge several boostbook into one, i want to try your approach.

As for dependencies, quickbook has parameter --output-deps (i suppose that this parameter appears since 1.5.8 version of quickbook), it is not very difficult to add this mechanism to CMake

пятница, 11 января 2013 г., 21:16:05 UTC+7 пользователь Mathias Gaunard написал:

[Alexey Kutumov]

I added initial support for generating `boostbook subset documentation` (from <src_root>/doc/src/boost.xml where located most of libraries), you can build documentation and install it (and see result in <install_prefix>/share/doc/html)

However i have several questions:

How to deal with already generated documentation (for example bind), or documentation which does not belongs to boost.xml (for example asio). I see obvious way to solve this problem - reproduce all hierarchy of documentation during `make install'. This question is important because CMake usuallly assume out-of-source building and i think that pollution of the source dir with generated documentation is not good.

Also i changed original <src_root>/doc/src/boost.xml - i changed locations of xi:include entries, but this can be easily fixed: xsltproc has ability to add search paths, so we can add this paths while generating boostbook documentation (fix corresponding jamfile), cmake build already has this feature. Is this critical?

пятница, 11 января 2013 г., 19:39:29 UTC+7 пользователь Daniel Pfeifer написал:

[Alexey Kutumov]

I want to check documentation under win32 without Cygwin, as i understand i need special version of xsltproc for win32, because "official" packages have win32 specific bug for creating directories (i tried latest binaries from http://www.boost.org/doc/libs/1_52_0/doc/html/boostbook/getting/started.html - they are still broken).

I found topic http://boost.2283326.n4.nabble.com/xsltproc-for-Windows-td2712518.html, but any links to meta-comm are broken, does anybody has these binaries?

понедельник, 14 января 2013 г., 1:01:23 UTC+7 пользователь Alexey Kutumov написал:

[Dave Abrahams]

on Fri Jan 18 2013, Alexey Kutumov <alexey.kutumov-AT-gmail.com> wrote:

> I want to check documentation under win32 without Cygwin, as i
> understand i need special version of xsltproc for win32, because
> "official" packages have win32 specific bug for creating directories
> (i tried latest binaries from http://www.boost.org/doc/libs/1_52_0/

> doc/html/boostbook/getting/started.html - they are still broken).

>
> I found topic http://boost.2283326.n4.nabble.com/
> xsltproc-for-Windows-td2712518.html, but any links to meta-comm are
> broken, does anybody has these binaries?

Aleksey might know how to fix the meta-comm link. Aleksey?

I don't know anything about this stuff, but Google suggested
http://www.zlatkovic.com/libxml.en.html

HTH,

[Alexey Kutumov]

Yes i tried xsltproc from http://www.zlatkovic.com/libxml.en.html, and it does not work, it has this issue

суббота, 19 января 2013 г., 0:05:52 UTC+7 пользователь Dave Abrahams написал:

[Alexey Kutumov]

I found solution: https://mail.gnome.org/archives/xslt/2011-December/msg00002.html

For correct work under win32 one must add "file://" prefix for any URL which passes to xsltproc, even any input and output files. I tried this approach and it works.

Thanks.

2013/1/19 Aleksey Gurtovoy <agur...@meta-comm.com>

On Fri, 18 Jan 2013 11:43:11 -0600, Alexey Kutumov <alexey....@gmail.com> wrote:

Yes i tried xsltproc from http://www.zlatkovic.com/libxml.en.html, and it
does not work, it has this issue

That's weird, the fix has been applied to the main branch ages ago:

  https://bugzilla.gnome.org/show_bug.cgi?id=462877

on Fri Jan 18 2013, Alexey Kutumov <alexey.kutumov-AT-gmail.com> wrote:

> I want to check documentation under win32 without Cygwin, as i
> understand i need special version of xsltproc for win32, because
> "official" packages have win32 specific bug for creating directories
> (i tried latest binaries from http://www.boost.org/doc/libs/1_52_0/
> doc/html/boostbook/getting/started.html - they are still broken).
>
> I found topic http://boost.2283326.n4.nabble.com/
> xsltproc-for-Windows-td2712518.html, but any links to meta-comm are
> broken, does anybody has these binaries?

Aleksey might know how to fix the meta-comm link.  Aleksey?

It appears we lost the original binaries during one of the website migrations. Sorry!

--
Aleksey Gurtovoy
MetaCommunications Engineering