Argonne National Laboratory

Experimental Physics and
Industrial Control System

2002  2003  2004  2005  2006  2007  2008  2009  2010  <20112012  2013  2014  2015  2016  2017  2018  2019  2020  Index 2002  2003  2004  2005  2006  2007  2008  2009  2010  <20112012  2013  2014  2015  2016  2017  2018  2019  2020 
<== Date ==> <== Thread ==>

Subject: RE: class library header file naming and install conventions
From: "Jeff Hill" <johill@lanl.gov>
To: "'Andrew Johnson'" <anj@aps.anl.gov>, <core-talk@aps.anl.gov>
Date: Tue, 15 Mar 2011 10:35:18 -0600
Maybe the library's Makefile looks something like this in the future?

LIBRARY=pdq

INC += pdq.h
INC_pdq += pdq/Xxxx.h
INC_pdq += pdq/Yyyy.h

Jeff
______________________________________________________
Jeffrey O. Hill           Email        johill@lanl.gov
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: core-talk-bounces@aps.anl.gov [mailto:core-talk-
> bounces@aps.anl.gov] On Behalf Of Jeff Hill
> Sent: Tuesday, March 15, 2011 10:21 AM
> To: 'Andrew Johnson'; core-talk@aps.anl.gov
> Subject: RE: class library header file naming and install conventions
> 
> > I would encourage considering the use of a standard tool like
> > doxygen, I think once you start writing in-line documentation it should
> > make future maintenance easier, although I've rarely used it myself
> because
> > introducing it after-the-fact is hard.
> 
> Such tools have been around for a long time. People were using them on
> the
> VAX when I started here in 1986. I'm sure they have learned a thing or
> two
> since then so perhaps I should look closer at doxygen. The argument for
> use
> of doxygen type programs is that programmers are more likely to work on
> their programming language source files, and so if we store the doc there
> also then maybe they will keep it current. There can also be a standard,
> consistent, format. The downside maybe is that every manual reads like a
> reference manual, and we are less likely to have a tutorial. We are maybe
> more likely to create human friendly documentation with concept
> structured
> indexes and html tables if the html is structured by a human?
> 
> Jeff
> ______________________________________________________
> Jeffrey O. Hill           Email        johill@lanl.gov
> 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: core-talk-bounces@aps.anl.gov [mailto:core-talk-
> > bounces@aps.anl.gov] On Behalf Of Andrew Johnson
> > Sent: Tuesday, March 15, 2011 9:55 AM
> > To: core-talk@aps.anl.gov
> > Subject: Re: class library header file naming and install conventions
> >
> > On Monday 14 March 2011 18:11:03 Jeff Hill wrote:
> > >
> > > 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
> >
> > Actually those should be $(INSTALL_LOCATION)/include/... since we do
> > support
> > installation outside of the Base tree if so configured.
> >
> > > 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?
> >
> > Using the new build layout in lp:~mdavidsaver/epics-base/reorg-src all
> > the
> > source and header files for the module would be in src/<something>/pdq
> > with a
> > master Makefile in src/<something> that pulls in a Makefile fragment
> from
> > src/<something>/pdq thus the pdq in the path is not redundant.  Note
> that
> > <something> can have multiple path components.
> >
> > > o The c/c++ files are named src/pdq/lib/Xxxx.cpp
> >
> > Like Ralph I don't see the purpose of the 'lib' part and it would
> > actually
> > break the new build layout.
> >
> > > 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)
> >
> > The documentation master should be with the source code in
> > src/<something>/pdq
> > from where (if it's included in the HTMLS variable) the current build
> > system
> > can install it into $(INSTALL_LOCATION)/html or I believe into a sub-
> > directory
> > named in the HTMLS_DIR variable, or (if it's included in the DOCS
> > variable)
> > into the $(INSTALL_LOCATION)/doc directory.
> >
> > As Ralph said, documentation should be installed (see the
> > INSTALL_LOCATION
> > point above).  I would encourage considering the use of a standard tool
> > like
> > doxygen, I think once you start writing in-line documentation it should
> > make
> > future maintenance easier, although I've rarely used it myself because
> > introducing it after-the-fact is hard.
> >
> > - Andrew
> > --
> > An error is only a mistake if you don't learn from it.
> > When you learn something from it, it becomes a lesson.




Replies:
Re: class library header file naming and install conventions Andrew Johnson
References:
class library header file naming and install conventions Jeff Hill
Re: class library header file naming and install conventions Andrew Johnson
RE: class library header file naming and install conventions Jeff Hill

Navigate by Date:
Prev: RE: class library header file naming and install conventions Jeff Hill
Next: Re: class library header file naming and install conventions Andrew Johnson
Index: 2002  2003  2004  2005  2006  2007  2008  2009  2010  <20112012  2013  2014  2015  2016  2017  2018  2019  2020 
Navigate by Thread:
Prev: RE: class library header file naming and install conventions Jeff Hill
Next: Re: class library header file naming and install conventions Andrew Johnson
Index: 2002  2003  2004  2005  2006  2007  2008  2009  2010  <20112012  2013  2014  2015  2016  2017  2018  2019  2020 
ANJ, 02 Feb 2012 Valid HTML 4.01! · Home · News · About · Base · Modules · Extensions · Distributions · Download ·
· Search · EPICS V4 · IRMIS · Talk · Bugs · Documents · Links · Licensing ·