EPICS Home

Experimental Physics and Industrial Control System


 
1994  1995  1996  1997  1998  1999  2000  2001  2002  2003  2004  2005  2006  2007  2008  2009  2010  <20112012  2013  2014  2015  2016  2017  2018  2019  Index 1994  1995  1996  1997  1998  1999  2000  2001  2002  2003  2004  2005  2006  2007  2008  2009  2010  <20112012  2013  2014  2015  2016  2017  2018  2019 
<== Date ==> <== Thread ==>

Subject: Re: class library header file naming and install conventions
From: Bruce Hill <bhill@slac.stanford.edu>
To: Jeff Hill <johill@lanl.gov>
Cc: "'EPICS core-talk'" <core-talk@aps.anl.gov>, "tech-talk@aps.anl.gov" <tech-talk@aps.anl.gov>
Date: Tue, 15 Mar 2011 14:02:34 -0700
Hi Jeff,
Thanks for putting together a straw-man on this.   I agree this
is an important topic and I'm glad you're addressing it.
I generally like what you've proposed, so I'll just add
a few comments below.

Regards,
- Bruce

On 03/14/2011 04:11 PM, 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
By Xxxx are you implying that class names start with upper case? EPICS seems to mostly have class names start with lower case and use camelCase for compound names,
so perhaps the strawman should use xxxYyyy as the example class name.
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?
I have no problem with pdq appearing twice in the path,
but I'm not sure why the lib directory is needed.
o The c/c++ files are named src/pdq/lib/Xxxx.cpp
Ditto here.    Why not:
src/pdq/xxxYyyy.cpp
src/pdq/pdq.h
src/pdq/pdq/xxxYyyy.h
src/pdq/doc/pdq.html
src/pdq/doc/pdq/xxxYyyy.html
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)

All comments appreciated.
Thanks,

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
--
Bruce Hill
Member Technical Staff
SLAC National Accelerator Lab
2575 Sand Hill Road M/S 10
Menlo Park, CA  94025



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: where to free memory in asub record? Andrew Johnson
Next: Re: How to use asyn with linux-GPIB Feng Laurence
Index: 1994  1995  1996  1997  1998  1999  2000  2001  2002  2003  2004  2005  2006  2007  2008  2009  2010  <20112012  2013  2014  2015  2016  2017  2018  2019 
Navigate by Thread:
Prev: class library header file naming and install conventions Jeff Hill
Next: RE: class library header file naming and install conventions Jeff Hill
Index: 1994  1995  1996  1997  1998  1999  2000  2001  2002  2003  2004  2005  2006  2007  2008  2009  2010  <20112012  2013  2014  2015  2016  2017  2018  2019