good continuous integration, automatic documentation software for c++

[Johnny Chang]

Started using trac and svn and it is working nicely, but am looking
for some other things to add: continuous integration, automatic
documentation. What suggestions do you guys have for the most full
featured easy to use software for this?

Stuff I am looking for:

build automation / continuous integration
-checkout, checkin working executable svn
-test framework for ease of testing - maybe define a test pattern, use
wildcards, any other features
-works fine without bugs for large compile and test times
-tests multiple clients
-can easily access files outside of svn server.

auto documentation
-extract comments to a html file
-linked source code documentation tree
-have forms or wiki that allows editing and propagates the changes
back into the source code as inline comments
-extraction of any other helpful information for large and complicated
code

comp.unix.programmer,comp.programming,comp.lang.c++,comp.std.c++


sourcecodesworld

 

[Bart van Ingen Schenau]

Started using trac and svn and it is working nicely, but am looking
for some other things to add: continuous integration, automatic
documentation. What suggestions do you guys have for the most full
featured easy to use software for this?

Stuff I am looking for:

build automation / continuous integration

auto documentation
-extract comments to a html file
-linked source code documentation tree
-have forms or wiki that allows editing and propagates the changes
back into the source code as inline comments
-extraction of any other helpful information for large and complicated
code

Doxygen (http://www.doxygen.org/) seems to cover most of your
requirements for the documentation.
What it does not do (and I am not aware of any other system that will do
it) is allow you to change the documentation and have that reflected in
the source code.

Bart v Ingen Schenau

 

[Maxim Yegorushkin]

Started using trac and svn and it is working nicely, but am looking
for some other things to add: continuous integration, automatic
documentation. What suggestions do you guys have for the most full
featured easy to use software for this?

Stuff I am looking for:

build automation / continuous integration
-checkout, checkin working executable svn
-test framework for ease of testing - maybe define a test pattern, use
wildcards, any other features
-works fine without bugs for large compile and test times
-tests multiple clients
-can easily access files outside of svn server.

auto documentation
-extract comments to a html file
-linked source code documentation tree
-have forms or wiki that allows editing and propagates the changes
back into the source code as inline comments
-extraction of any other helpful information for large and complicated
code

GNU make, Doxygen and something like CruiseControl (not
CruiseControl.rb crap though).

What you need to do is to create test and release targets in your
Makefile. test will do the tests, release will do the tests, extract
documentation using Doxygen and whatever else you want it to do.
CruiseControl will watch for changes in Subversion, check them out and
invoke `make test` or `make release`.

 

[James Kanze]

Doxygen (http://www.doxygen.org/) seems to cover most of your
requirements for the documentation. What it does not do (and
I am not aware of any other system that will do it) is allow
you to change the documentation and have that reflected in the
source code.

But that is really the most important feature. Normally,
documentation precedes the code, and is used to generate the
code---the inverse is really only used to recover legacy code
which wasn't written this way to begin with. Most of the
"expensive" tools (Rational Rose, Borland Together, etc.)
support this round trip engineering.

Although designed with C in mind, CWeb is worth looking into.

 

[Rainer Weikusat]

[...]

Normally, documentation precedes the code, and is used to generate
the code

[...]

Something which is used as input to an automated translation process
which ultimatively produces some kind of executable (or something
which can be used as part of such an executable, eg a shared library
or a Perl module) is by definition 'source code'.

 

[Chris Dollin]

[...]

Normally, documentation precedes the code, and is used to generate
the code

[...]

Something which is used as input to an automated translation process
which ultimatively produces some kind of executable (or something
which can be used as part of such an executable, eg a shared library
or a Perl module) is by definition 'source code'.

The usual documentation => code process isn't automated.

[Is electricity source code? How about time and energy? I think your
definition needs decolandering.]

 

[Bart van Ingen Schenau]

But that is really the most important feature. Normally,
documentation precedes the code, and is used to generate the
code---the inverse is really only used to recover legacy code
which wasn't written this way to begin with. Most of the
"expensive" tools (Rational Rose, Borland Together, etc.)
support this round trip engineering.

I have never had the privilege to really work with those integrated
design tools, so I can't tell how good they really are.
The practice I have come across the most is to write the documentation
before the code, but to have them in different files.

To my knowledge, tools like Rational Rose are designed to work with a
process where you first create a design of your application and then let
the tool create the source code from your design. In my experience, the
effort needed to fill-in all the little details, that are between a
design that is understandable for humans and one that can be used for
code generation, in considered too much.

That such tools can reverse-engineer source code to retrieve something
that looks like a design is just an added bonus for using them on legacy
projects, because the primary means of maintenance would be through the
tool itself.

Although designed with C in mind, CWeb is worth looking into.

Bart v Ingen Schenau

 

[James Kanze]

[...]

Normally, documentation precedes the code, and is used to
generate the code

[...]

Something which is used as input to an automated translation
process which ultimatively produces some kind of executable
(or something which can be used as part of such an executable,
eg a shared library or a Perl module) is by definition 'source
code'.

For some arbitrary and ultimately useless definition of "source
code", perhaps. CWeb input is certainly a sort of "source
code", but it's a lot more human readable than C++. And I don't
even know how to qualify things like Rose, in which the input
isn't in textual form (or isn't completely in textual form).

And of course, the code generation isn't always "an automated
translation process", although one does like to have parts of it
automated.

 

[Rainer Weikusat]

[...]

Normally, documentation precedes the code, and is used to
generate the code

[...]

Something which is used as input to an automated translation
process which ultimatively produces some kind of executable
(or something which can be used as part of such an executable,
eg a shared library or a Perl module) is by definition 'source
code'.

For some arbitrary and ultimately useless definition of "source
code", perhaps.

I didn't expect that you would be particularly fond of the remark that
what you believe to be 'really different' from programming is just
that, but that doesn't make it any different.

CWeb input is certainly a sort of "source code", but it's a lot more
human readable than C++.

And C++ is a lot more 'humanly readable' than assembler mnemonics,
which are more humanly readable than sequences of hexadecimal bytes
which are more humanly readable than strings of ones and zeroes and
....

And I don't even know how to qualify things like Rose, in which the
input isn't in textual form (or isn't completely in textual form).

"The aliterate's wheelchair"?

 

[Johnny Chang]

What does this software do? I'm just looking for automatic
documentation that lets you add comments to the source code from the
webpage/wiki, not actually edit the code. I'm sorry if I've
misunderstood

 

[James Kanze]

[...]
Normally, documentation precedes the code, and is used to
generate the code
[...]
Something which is used as input to an automated translation
process which ultimatively produces some kind of executable
(or something which can be used as part of such an executable,
eg a shared library or a Perl module) is by definition 'source
code'.

For some arbitrary and ultimately useless definition of
"source code", perhaps.

I didn't expect that you would be particularly fond of the
remark that what you believe to be 'really different' from
programming is just that, but that doesn't make it any
different.

It's not a question of fond or not. The remark doesn't mean
anything unless you define what you mean by "source code". In
some sense, everything is "source code": LaTeX is "compiled" to
produce a book, Shakespeare's manuscripts are (manually)
compiled to create a play, etc., etc.

The difference is that C++ source code is principally designed
to be fed to a compiler. Things like CWeb source code are
designed to both generate documentation and generate code which
can be fed to a C or a C++ compiler (and include much more
text).

You're just playing word games.

And C++ is a lot more 'humanly readable' than assembler
mnemonics, which are more humanly readable than sequences of
hexadecimal bytes which are more humanly readable than strings
of ones and zeroes and
...

Never the less, almost all of C++'s grammar is designed for the
compiler. And the plain English parts (comments) must be
specially marked and delimited, so that the compiler knows to
ignore them. In CWeb, it's just the opposite: the body of the
document is in plain English, and it is the parts that will be
interpreted by the various compilers (LaTeX, C++) that must be
specially marked.

"The aliterate's wheelchair"?

And that is about the most stupid remark I've heard yet.
There's an old saying: a picture is worth a thousand words.
Some types of information are best communicated graphically,
others in native language. My real complain with the currently
available systems is that I don't know of any which support both
seemlessly: integrating graphics (class diagrams, etc.) into
CWeb is a real pain, and Rose doesn't do much to support English
text. In my own experience, Rose works out better, but you
still need considerable additional documentation in LaTeX or
HTML. That may be partially because I've worked on a lot of
large projects using Rose, but my knowledge of CWeb is much more
limited. But class diagrams are essential at some point, and
they really have to be done before you can start coding.

 

[James Kanze]

What does this software do? I'm just looking for automatic
documentation that lets you add comments to the source code from the
webpage/wiki, not actually edit the code. I'm sorry if I've
misunderstood

Which software?

Rose generates the code framework (class definitions, bodiless
functions, etc.) from the class diagrams; you then have to add
the function bodies. I've seen it used in three different ways:
as a simple documentation tool, without any relationship to the
source code, as an interface specification tool as well, with
fully automatic generation of the header files (which were
declared as "derived" objects in the version control system, and
couldn't be manually edited), or for complete round trip
engineering, where both the sources and the headers were
generated by Rose.

CWeb is, of course, Knuth and Levy's literate programming tool.

I've extensive experience with Rose, and find it very effective,
although it can be frustrating for things best expressed in
English, rather than through diagrams. I've not enough
experience with CWeb to judge much, but I have the impression
that the problem will be just the opposite: CWeb doesn't have
any support for graphics. In addition, at least from what
little I've seen, CWeb doesn't have any provisions for round
trip engineering: in Rose, you write the function bodies
directly in C++, in your favorite editor, and Rose uses various
techniques to keep what you've added when you regenerate the
code. In CWeb, if I've understood correctly, you must either
write everything in CWeb (including the function bodies), or
loose any modifications you've made anytime you regenerate.
This would work for the model where you generate just the header
files (and they are never edited by humans), but C++ is rather
verbose, and it's nice to have the empty functions generated
automatically in the source file as well.

 

[Rainer Weikusat]

[...]
Normally, documentation precedes the code, and is used to
generate the code
[...]
Something which is used as input to an automated translation
process which ultimatively produces some kind of executable
(or something which can be used as part of such an executable,
eg a shared library or a Perl module) is by definition 'source
code'.
For some arbitrary and ultimately useless definition of
"source code", perhaps.

I didn't expect that you would be particularly fond of the
remark that what you believe to be 'really different' from
programming is just that, but that doesn't make it any
different.

It's not a question of fond or not. The remark doesn't mean
anything unless you define what you mean by "source code". In
some sense, everything is "source code": LaTeX is "compiled" to
produce a book, Shakespeare's manuscripts are (manually)
compiled to create a play, etc., etc.

The difference is that C++ source code is principally designed
to be fed to a compiler.

This is principally complete nonsense: Like all higher-level
programming languages, C++ was designed by humans in order to enable
other humans to program a computer more easily (and it took the
g++-project more than thirteen years to come up with an 'almost
complete' parser for it) [as would be possible when using C[*]].

[*] if and to which degree this goal has been accomplished
would be another question.

But that's actually a suspicion I already had yesterday: Since, to the
C++-monolingualist, there is only one programming language, namely,
C++, everything which isn't written in C++ is not written using 'the
programming language', hence, it cannot be 'source code'.

[...]

And that is about the most stupid remark I've heard yet.
There's an old saying: a picture is worth a thousand words.

Can I have a picture of the Code Napeoleon?

 

[James Kanze]

[...]

This is principally complete nonsense: Like all higher-level
programming languages, C++ was designed by humans in order to
enable other humans to program a computer more easily (and it
took the g++-project more than thirteen years to come up with
an 'almost complete' parser for it) [as would be possible when
using C[*]].

Which is orthogonal to what I said.

But that's actually a suspicion I already had yesterday:
Since, to the C++-monolingualist, there is only one
programming language, namely, C++, everything which isn't
written in C++ is not written using 'the programming
language', hence, it cannot be 'source code'.

I wouldn't know about that, since I don't know anyone who is
monolingual in C++. Most of the people I know speak French,
German or English (or several of the above). And don't usually
consider French, German or English "source code".

 

[coal]

[...]
Normally, documentation precedes the code, and is used to
generate the code
[...]
Something which is used as input to an automated translation
process which ultimatively produces some kind of executable
(or something which can be used as part of such an executable,
eg a shared library or a Perl module) is by definition 'source
code'.
For some arbitrary and ultimately useless definition of
"source code", perhaps.
I didn't expect that you would be particularly fond of the
remark that what you believe to be 'really different' from
programming is just that, but that doesn't make it any
different.

It's not a question of fond or not.  The remark doesn't mean
anything unless you define what you mean by "source code". In
some sense, everything is "source code": LaTeX is "compiled" to
produce a book, Shakespeare's manuscripts are (manually)
compiled to create a play, etc., etc.

The difference is that C++ source code is principally designed
to be fed to a compiler.

This is principally complete nonsense: Like all higher-level
programming languages, C++ was designed by humans in order to enable
other humans to program a computer more easily (and it took the
g++-project more than thirteen years to come up with an 'almost
complete' parser for it) [as would be possible when using C[*]].

        [*] if and to which degree this goal has been accomplished
        would be another question.

But that's actually a suspicion I already had yesterday: Since, to the
C++-monolingualist, there is only one programming language, namely,
C++, everything which isn't written in C++ is not written using 'the
programming language', hence, it cannot be 'source code'.

That sounds like sour grapes to me. Those who like using C++
need not apologize for its ongoing success. I may be the
staunchest C++ monolingualist in these parts. I shun the
use of PERL and such. It is too insidious. A ten line PERL
script looks harmless enough, but soon it would be a 200 line
mess.


Brian Wood
Ebenezer Enterprises
www.webEbenezer.net


"All the world is just a narrow bridge. The most important
thing is not to be afraid." Rebbe Nachman

 

[Rainer Weikusat]

On Jun 4, 3:24 pm, Rainer Weikusat <[email protected]> wrote:

[...]

It's not a question of fond or not. The remark doesn't mean
anything unless you define what you mean by "source code". In
some sense, everything is "source code": LaTeX is "compiled" to
produce a book, Shakespeare's manuscripts are (manually)
compiled to create a play, etc., etc.
The difference is that C++ source code is principally designed
to be fed to a compiler.

This is principally complete nonsense: Like all higher-level
programming languages, C++ was designed by humans in order to
enable other humans to program a computer more easily (and it
took the g++-project more than thirteen years to come up with
an 'almost complete' parser for it) [as would be possible when
using C[*]].

Which is orthogonal to what I said.

You may believe that 'C++ was principally designed to be fed to a
compiler' and 'C++ was designed to be easy to use by humans' are
unrelated statements, but that would be a misunderstanding or (more
likely) a deliberate misinterpretation.

I wouldn't know about that, since I don't know anyone who is
monolingual in C++.

In this particular case, you should be asking me what I intended to
express instead of assuming that you can just make up a meaning which
is convenient for you. But I believe you understood me all to well.

But this is a side issue. The core of my original statement was
supposed to be that 'using Rational-whatever to produce input for some
program which then creates C++ from that as one of the steps which
ultimatively end up creating an executable program' is not genuinely
different from using any other programming language, ie if
'documentation is used to create code', this documentation should
sensibly be referred to as [source] code, too. This does not preclude
this 'documentation language' to be better suited for a particular
task than $random_other_language (although it doesn't imply that it
is so, either).

For almost 40 years, people have been anticipating and writing
about "automatic programming, " or the generation of a program
for solving a problem from a statement of the problem
specifications. Some today write as if they expect this
technology to provide the next breakthrough 5

Parnas 4 implies that the term is used for glamour, not for
semantic content, asserting,

In short, automatic programming always has been a euphemism
for programming with a higher-level language than was
presently available to the programmer.
[http://www.virtualschool.edu/mon/SoftwareEngineering/BrooksNoSilverBullet.html]

And my personal opinion regarding this 'euphemisms' is that they are a
throroughly bad thing, if only because they generate irrational
resistance to 'more modern technologies' (in areas where they actually
make sense).

 

[Bart van Ingen Schenau]

[...]

Normally, documentation precedes the code, and is used to
generate the code

[...]

Something which is used as input to an automated translation
process which ultimatively produces some kind of executable
(or something which can be used as part of such an executable,
eg a shared library or a Perl module) is by definition 'source
code'.

For some arbitrary and ultimately useless definition of "source
code", perhaps.

Would you call the definition of 'source code' as used in the GPL
license to be useless?
The GPL defines source code as:
<quote>
The ?source code? for a work means the preferred form of the work for
making modifications to it. ?Object code? means any non-source form of a
work.

CWeb input is certainly a sort of "source
code", but it's a lot more human readable than C++. And I don't
even know how to qualify things like Rose, in which the input
isn't in textual form (or isn't completely in textual form).

Under the GPL definition, both CWeb input and Rose models would count as
source code, if it is a preferred way of making modifications to the
program.
Human readability or if it is in textual form does not affect if it
can/should be considered source code.

Bart v Ingen Schenau

 

[James Kanze]

On Jun 4, 3:24 pm, Rainer Weikusat <[email protected]> wrote:

[...]
I wouldn't know about that, since I don't know anyone who is
monolingual in C++.

In this particular case, you should be asking me what I
intended to express instead of assuming that you can just make
up a meaning which is convenient for you. But I believe you
understood me all to well.

I'm really not sure. As I said, I don't know anyone who is
monolingual in C++, or even uses it as a first language. And
that is the key to my point.

But this is a side issue. The core of my original statement
was supposed to be that 'using Rational-whatever to produce
input for some program which then creates C++ from that as one
of the steps which ultimatively end up creating an executable
program' is not genuinely different from using any other
programming language, ie if 'documentation is used to create
code', this documentation should sensibly be referred to as
[source] code, too. This does not preclude this 'documentation
language' to be better suited for a particular task than
$random_other_language (although it doesn't imply that it is
so, either).

OK. In a certain (very real) sense, this is true. And Rose or
CWeb are still somewhat removed from English. In the case of
Rose, of course, this is intentional---the goal is to input UML,
not English, and UML is still another language, which has to be
learned. And UML, while very good at expressing higher level
relationships, provides no support for expressing the lowest
level---the code in each function, so Rose won't generate this
for you. In the case of CWeb, the distance is considerably
less---CWeb is designed to produce English (or French or
whatever) documents; it differs from "plain English" mainly in
containing markup. It also requires that all of the C++ which
ends up in the C++ source file appear literally in the CWeb
source; in this sense, it doesn't "compile" the CWeb source to
C++; it just extracts the parts marked up as C++ (and reorders
them).

For almost 40 years, people have been anticipating and
writing about "automatic programming, " or the
generation of a program for solving a problem from a
statement of the problem specifications. Some today
write as if they expect this technology to provide the
next breakthrough 5

Parnas 4 implies that the term is used for glamour,
not for semantic content, asserting,

In short, automatic programming always has been a
euphemism for programming with a higher-level language
than was presently available to the programmer.
[http://www.virtualschool.edu/mon/SoftwareEngineering/BrooksNoSilverBu...]

And my personal opinion regarding this 'euphemisms' is that
they are a throroughly bad thing, if only because they
generate irrational resistance to 'more modern technologies'
(in areas where they actually make sense).

I totally agree with this sentiment---the worst thing about them
being, of course, that they lead higher management to expect
miracles. But I don't pretend that Rose or CWeb are "automatic
programming tools". All I was trying to say is that the
"documentation" should precede the actual coding (in C++ or
whatever), and that there are tools which support the extraction
of some (or in the case of CWeb, all) of the C++ source code
from the "documentation". If you want to call such
documentation "source code", you can---and there's certainly a
sense in which you're correct. But there is still a significant
difference between a UML diagram or a CWeb document and C++ or
another "programming language". And while it's true that part
of C++ is designed to be read by humans, and not just the
compiler, it's also designed with the idea that it somehow
expresses the actions the program should take; tools like Rose
or CWeb start from the idea that we should start at a higher
level, and maintain higher level design considerations in the
same file as the program code. And that's something I find
useful.

 

[James Kanze]

[...]
Normally, documentation precedes the code, and is used to
generate the code
[...]
Something which is used as input to an automated
translation process which ultimatively produces some kind
of executable (or something which can be used as part of
such an executable, eg a shared library or a Perl module)
is by definition 'source code'.

For some arbitrary and ultimately useless definition of
"source code", perhaps.

Would you call the definition of 'source code' as used in the
GPL license to be useless?
The GPL defines source code as:
<quote>
The ?source code? for a work means the preferred form of the
work for making modifications to it. ?Object code? means any
non-source form of a
work.
</quote>

Utility depends on context. In this case, the GPL is making an
arbitrary definition for use in a very specific legal context.

Under the GPL definition, both CWeb input and Rose models
would count as source code, if it is a preferred way of making
modifications to the program.

Legally, yes. But the GPL definition is designed for use in a
very restricted legal context.

Human readability or if it is in textual form does not affect
if it can/should be considered source code.

I would mainly agree with that. The difference which I find
important here is what the "source code" is expressing. If it
is expressing mainly information needed by the machine, even if
it is doing so in a way which is very round-about from the
machines point of view, then it is what I meant by "source
code". If it is mainly expressing information irrelevant to the
machine, but important for human beings to understand the code,
then we're dealing with something else. Also a "source", if you
prefer (and now that I understand Rainer's point, I agree with
it), but it is something different from C or C++. Even more so,
IMHO, than C and C++ are different from assembler.

 

[Rainer Weikusat]

[...]

The difference is that C++ source code is principally designed
to be fed to a compiler.

This is principally complete nonsense: Like all higher-level
programming languages, C++ was designed by humans in order to enable
other humans to program a computer more easily (and it took the
g++-project more than thirteen years to come up with an 'almost
complete' parser for it) [as would be possible when using C[*]].

        [*] if and to which degree this goal has been accomplished
        would be another question.

But that's actually a suspicion I already had yesterday: Since, to the
C++-monolingualist, there is only one programming language, namely,
C++, everything which isn't written in C++ is not written using 'the
programming language', hence, it cannot be 'source code'.

That sounds like sour grapes to me.

I do not quite understand how the fact that a certain (and fairly
large although shrinking) set of people isn't willing or capable of
ever using another programming language except one they accidentally
happen to have learnt to some degree could negatively affect me.

Those who like using C++ need not apologize for its ongoing success.

This, too, doesn't seem to have any relation to the content of my
statement.

I may be the staunchest C++ monolingualist in these parts.

Sincere condolences. But I still don't understand what you are up
to.

I shun the use of PERL and such. It is too insidious. A ten line
PERL script looks harmless enough, but soon it would be a 200 line
mess.

I you already manage to create 'a mess' in the form of something as
innocent as a microsopic script (200 lines), that would be your
problem. I estimate that I have something like 25,000 LOC of Perl-code
laying around here, with the size of any single program usually
between 3,500 and 6,500 LOC and haven't found any insurmountable
difference in applying the same rules for structuring source code
sensibly to that than to code written in any other language.