Experimental Physics and
Industrial Control System

"Jeff Hill" <[email protected]> · Tue, 15 Mar 2011 10:06:10 -0600

> Change the build system to use a simpler path.

Agree, but maybe we have to also convince Janet - because she will
coordinate the work (I hope :-).

> If pdq consists of the library, nothing else, I would even skip the /lib/
> part of the path.

After further consideration "src", might be a better path name than "lib",
or we could just place all of the Xxxx.cpp and Xxxx.h in at the same level
as test and doc as you suggest. My first choice would be to place the source
files in "pdq/src", but I am ok with what you suggest also (directly under
"pdq").

> Documentation should be installed.

Yes, and in-fact they are already installed by the build. 

> > o The documentation master goes in src/pdq/doc/pdq.html
> > o Maybe the class interface documentation goes in
> src/pdq/doc/pdq/Xxxx.html
> > (same concerns about redundant pdq in the path)

I was thinking (sorry I didn?t fully elaborate on my thoughts) that there
are parallels between C headers and the html doc. With C headers we can have
a relative path i.e. "#include "pdq/Xxxx.h". With html we can have, as I
recall, a website self-relative link like this "<a href="pdq/Xxxx.html"> the
chapter on Xxxx</a>" so we are not required to maintain a monolithic html
file. So presumably we could have pdq.html installed to $(EPICS_BASE)/doc
and Xxxx.html installed to $(EPICS_BASE)/doc/pdq/Xxxx.html. A somewhat
parallel situation to what is proposed with header files, and maybe with
similar implications for the install part of the build system.

> We should also have a standard place for unit tests for libraries.
> Probably src/pdq/test for your example.

Agree. So we have now {test, doc, src, ...} or alternatively {test, doc,
Xxxx.cpp, Xxxx.h, Yyyy.cpp, Yyyy.h, ...} as you have suggested. And, again,
if the headers are installed from "pdq/src" or "pdq" into
"$(EPICS_BASE)/include/pdq" and sometimes "$(EPICS_BASE)/include" then maybe
we will need to make some changes in the build system. 

Jeff
______________________________________________________
Jeffrey O. Hill           Email        [email protected]
LANL MS H820              Voice        505 665 1831
Los Alamos NM 87545 USA   FAX          505 665 5107

Message content: TSPA

With sufficient thrust, pigs fly just fine. However, this is
not necessarily a good idea. It is hard to be sure where they
are going to land, and it could be dangerous sitting under them
as they fly overhead. -- RFC 1925

> -----Original Message-----
> From: [email protected] [mailto:core-talk-
> [email protected]] On Behalf Of Ralph Lange
> Sent: Tuesday, March 15, 2011 5:42 AM
> To: 'EPICS core-talk'
> Subject: Re: class library header file naming and install conventions
> 
> On 15.03.2011 00:11 Jeff Hill wrote:
> > All,
> >
> > When designing a C++ class library whose name is pdq it seems that one
> might
> > implement one header file for every exported class, and follow some
> naming
> > rules.
> >
> > Here is a straw-man. Lots of other schemes are possible, and the only
> really
> > bad scheme is to follow no naming convention at all, I suppose.
> >
> > o The C++ namespace is pdq (class lib names must be all lower case
> letters)
> > o The master header file's name is pdq.h
> > o Each exported class named Xxxx has a header file named pdq/Xxxx.h
> > o The master header file has '#include "pdq/Xxxx.h"' for each exported
> class
> > o The pdq.h is installed to $(EPICS_BASE)/include/pdq.h
> > o The pdq/Xxxx.h are installed to $(EPICS_BASE)/include/pdq/Xxxx.h
> > o The build system appears to implement this type of install now if, in
> the
> > build area, one has something like src/pdq/lib/pdq which contains the
> header
> > files (where they are installed from). Is that what we want? That
> (redundant
> > pdq in the path) could be initially somewhat confusing to the
> uninitiated,
> > and I don?t see any reason to place the header files in a subdirectory
> other
> > than to avoid changing the build system?
> 
> Change the build system to use a simpler path.
> 
> > o The c/c++ files are named src/pdq/lib/Xxxx.cpp
> 
> If pdq consists of the library, nothing else, I would even skip the /lib/
> part of the path.
> 
> > o The documentation master goes in src/pdq/doc/pdq.html
> > o Maybe the class interface documentation goes in
> src/pdq/doc/pdq/Xxxx.html
> > (same concerns about redundant pdq in the path)
> 
> Documentation should be installed. (To allow for documentation to be
> generated from the source files, e.g. Doxygen. And to make creating
> binary
> packages easier.)
> Probably into $(EPICS_BASE)/doc/pdq.
> 
> We should also have a standard place for unit tests for libraries.
> Probably src/pdq/test for your example.
> 
> Cheers,
> ~Ralph

Experimental Physics and Industrial Control System

Experimental Physics and
Industrial Control System