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: Andrew Johnson <anj@aps.anl.gov>
To: core-talk@aps.anl.gov
Date: Tue, 15 Mar 2011 09:55:24 -0600
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 Jeff Hill
References:
class library header file naming and install conventions Jeff Hill

Navigate by Date:
Prev: Re: class library header file naming and install conventions Ralph Lange
Next: RE: class library header file naming and install conventions Jeff Hill
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 Jeff Hill
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 ·