You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficserver.apache.org by Leif Hedstrom <zw...@apache.org> on 2010/02/04 05:08:51 UTC
[vote] Final API file names and include dir names
So, I think the discussions have had enough time, the consensus is
definitely that we should clean up what we got. As such, we will move
both include files to be in the same directory in SVN, we will rename
RemapAPI.h to remap_api.h, and we will install the two header files in a
well defined include directory. Two things to vote on remains (please
cast votes within 72 hours):
InkApi.h rename:
------------------------
[ ] api.h
[ ] ts_api.h
[ ] sdkapi.h
Include directory name
---------------------------------
[ ] ${prefix}/ts
[ ] ${prefix}/trafficserver
Include directives would hence look like the examples below (depending
on the outcome of the votes):
#include <ts/remap_api.h>
#include <ts/api.h> -- or --
#include <ts/ts_api.h> -- or --
#include <ts/sdkapi.h>
-- or --
#include <trafficserver/remap_api.h>
#include <trafficserver/api.h> -- or --
#include <trafficserver/ts_api.h> -- or --
#include <trafficserver/sdkapi.h>
Cheers!
-- Leif
Re: [vote] Final API file names and include dir names
Posted by Leif Hedstrom <zw...@apache.org>.
My votes are:
>
> InkApi.h rename:
> ------------------------
> [x] api.h
> [ ] ts_api.h
> [ ] sdkapi.h
>
>
> Include directory name
> ---------------------------------
>
> [x] ${prefix}/ts
> [ ] ${prefix}/trafficserver
-- Leif
Re: [vote] Final API file names and include dir names
Posted by John Plevyak <jp...@acm.org>.
I second that:
InkApi.h rename:
------------------------
[ ] api.h
[X] ts_api.h
[ ] sdkapi.h
Include directory name
---------------------------------
[X] ${prefix}/ts
[ ] ${prefix}/trafficserver
On 2/3/2010 9:27 PM, Tin Zaw wrote:
> InkApi.h rename:
> ------------------------
> [ ] api.h
> [X] ts_api.h
> [ ] sdkapi.h
>
>
> Include directory name
> ---------------------------------
>
> [X] ${prefix}/ts
> [ ] ${prefix}/trafficserver
>
>
>
>
> ________________________________
> From: Leif Hedstrom <zw...@apache.org>
> To: trafficserver-dev@incubator.apache.org
> Sent: Wed, February 3, 2010 8:08:51 PM
> Subject: [vote] Final API file names and include dir names
>
> So, I think the discussions have had enough time, the consensus is definitely that we should clean up what we got. As such, we will move both include files to be in the same directory in SVN, we will rename RemapAPI.h to remap_api.h, and we will install the two header files in a well defined include directory. Two things to vote on remains (please cast votes within 72 hours):
>
>
> InkApi.h rename:
> ------------------------
> [ ] api.h
> [ ] ts_api.h
> [ ] sdkapi.h
>
>
> Include directory name
> ---------------------------------
>
> [ ] ${prefix}/ts
> [ ] ${prefix}/trafficserver
>
>
>
> Include directives would hence look like the examples below (depending on the outcome of the votes):
>
> #include <ts/remap_api.h>
> #include <ts/api.h> -- or --
> #include <ts/ts_api.h> -- or --
> #include <ts/sdkapi.h>
>
> -- or --
>
> #include <trafficserver/remap_api.h>
> #include <trafficserver/api.h> -- or --
> #include <trafficserver/ts_api.h> -- or --
> #include <trafficserver/sdkapi.h>
>
>
> Cheers!
>
> -- Leif
Re: [vote] Final API file names and include dir names
Posted by Tin Zaw <tz...@yahoo.com>.
InkApi.h rename:
------------------------
[ ] api.h
[X] ts_api.h
[ ] sdkapi.h
Include directory name
---------------------------------
[X] ${prefix}/ts
[ ] ${prefix}/trafficserver
________________________________
From: Leif Hedstrom <zw...@apache.org>
To: trafficserver-dev@incubator.apache.org
Sent: Wed, February 3, 2010 8:08:51 PM
Subject: [vote] Final API file names and include dir names
So, I think the discussions have had enough time, the consensus is definitely that we should clean up what we got. As such, we will move both include files to be in the same directory in SVN, we will rename RemapAPI.h to remap_api.h, and we will install the two header files in a well defined include directory. Two things to vote on remains (please cast votes within 72 hours):
InkApi.h rename:
------------------------
[ ] api.h
[ ] ts_api.h
[ ] sdkapi.h
Include directory name
---------------------------------
[ ] ${prefix}/ts
[ ] ${prefix}/trafficserver
Include directives would hence look like the examples below (depending on the outcome of the votes):
#include <ts/remap_api.h>
#include <ts/api.h> -- or --
#include <ts/ts_api.h> -- or --
#include <ts/sdkapi.h>
-- or --
#include <trafficserver/remap_api.h>
#include <trafficserver/api.h> -- or --
#include <trafficserver/ts_api.h> -- or --
#include <trafficserver/sdkapi.h>
Cheers!
-- Leif
Re: [vote] Final API file names and include dir names
Posted by Leif Hedstrom <le...@ogre.com>.
On 02/04/2010 12:31 PM, Jason wrote:
> I'd like to voice a comment,
>
> ${prefix}/ts seems somewhat vague unless you were going to rename all the
> scripts ts.
>
> My eyes can read quite clear exactly what this header is even if i had no
> idea what trafficserver was and just happened to be reading some random
> piece of code:
> "#include<trafficserver/sdkapi.h>"
>
I'm not sure I understand why the two include files (which would be used
by a very small minority of TS users, those who actually implements new
plugins, or debug existing plugins) should have any impact on what the
names of the scripts or "binaries" are? That much said, I can certainly
understand the argument for "readability" for the common user, but do we
care about that for these low level APIs?
My personal thought for suggesting /ts/ was to keep it short and clean
in the "namespace".
Cheers,
-- Leif
Re: [vote] Final API file names and include dir names
Posted by Jason <ja...@gmail.com>.
I'd like to voice a comment,
${prefix}/ts seems somewhat vague unless you were going to rename all the
scripts ts.
My eyes can read quite clear exactly what this header is even if i had no
idea what trafficserver was and just happened to be reading some random
piece of code:
"#include <trafficserver/sdkapi.h>"
Just some thoughts,
- Jason
On Wed, Feb 3, 2010 at 11:08 PM, Leif Hedstrom <zw...@apache.org> wrote:
> So, I think the discussions have had enough time, the consensus is
> definitely that we should clean up what we got. As such, we will move both
> include files to be in the same directory in SVN, we will rename RemapAPI.h
> to remap_api.h, and we will install the two header files in a well defined
> include directory. Two things to vote on remains (please cast votes within
> 72 hours):
>
>
> InkApi.h rename:
> ------------------------
> [ ] api.h
> [ ] ts_api.h
> [ ] sdkapi.h
>
>
> Include directory name
> ---------------------------------
>
> [ ] ${prefix}/ts
> [ ] ${prefix}/trafficserver
>
>
>
> Include directives would hence look like the examples below (depending on
> the outcome of the votes):
>
> #include <ts/remap_api.h>
> #include <ts/api.h> -- or --
> #include <ts/ts_api.h> -- or --
> #include <ts/sdkapi.h>
>
> -- or --
>
> #include <trafficserver/remap_api.h>
> #include <trafficserver/api.h> -- or --
> #include <trafficserver/ts_api.h> -- or --
> #include <trafficserver/sdkapi.h>
>
>
> Cheers!
>
> -- Leif
>
>
Re: [vote] Final API file names and include dir names
Posted by Leif Hedstrom <zw...@apache.org>.
On 02/03/2010 09:08 PM, Leif Hedstrom wrote:
>
> Include directory name
> ---------------------------------
>
> [ ] ${prefix}/ts
> [ ] ${prefix}/trafficserver
I'm an idiot, but I'm hoping everyone realized the above was a typo, the
directory names would obviously be one of
${prefix}/include/ts
${prefix}/include/trafficserver
e.g. /usr/local/include/ts or /usr/local/include/trafficserver. If this
changes any of your previous votes, just annul and vote again.
Thanks,
-- Leif
Re: [vote] Final API file names and include dir names
Posted by Leif Hedstrom <zw...@apache.org>.
One more thing I'd like to briefly discuss.
After working on the SimpleDBM class, I realized that this could
actually be very useful to expose to plugin developers. It simplifies
the usage of simple key-val DBs, and provides a unified and installation
independent abstraction for the plugin to use.
So, I'd like to amend the API proposal/discussion with the addition of
simple_dbm.h (file renamed) to the API include directory. We'll mark
this file as "experimental", with no guarantees that we won't break ABI
or APIs until the 3.0 release.
If there are no -1 objections in this discussion, I'll add it to the
proposal which we'll vote on in a few days. If there are objections,
I'll simply leave it out to not make the vote more complex that
necessary, and revisit this again for 3.0.
Thoughts?
-- leif
P.s
For Yahoos: This would make it easier for at least a couple of our
plugins to "abstract" away dependencies we have on internal databases.
I.e. we can "patch" the SimpleDBM to support our internal databases for
our internal build, and to the plugin it'll be transparent (just a
recompile). Not an ideal solution, but better than nothing, and we have
more chance of releasing plugins without making lots of changes /
#ifdef's to the plugin code.
Re: [vote] Final API file names and include dir names
Posted by Leif Hedstrom <le...@ogre.com>.
On 02/04/2010 09:43 PM, Leif Hedstrom wrote:
>
> The above would make it pretty darn easy to compile for multiple
> versions, just change the /active/ symlink accordingly.
I should say, it gives several options for building for multiple versions:
1) Change the symlink (in my modified proposal).
2) Explicitly specify a -I/usr/local/include/ats/2.0
3) Change code to do #include <ats/2.0/api.h> or #include <ats/3.0/api.h>
Just saying, the proposal from John gives several options for someone
who wants to handle multiple versions when building plugins.
Cheers,
-- Leif
Re: [vote] Final API file names and include dir names
Posted by Leif Hedstrom <zw...@apache.org>.
On 02/04/2010 05:04 PM, John Plevyak wrote:
>
> Another question is how do we want to handle versions? Should we have:
>
> ats/ats-2.0.h ?
>
> gtk uses /usr/include/gtk-2.0
> python in /usr/include/python2.5
> gcc uses /usr/include/g++/4.1.2
>
> Some folks also have a single .h which pulls in everything:
>
We touched on this issue before, and I'm not sure it's really necessary?
I mean, the reason why things like gtk version their stuff is because
both users and developers are quite likely to have applications that
need different versions of the include /libraries. So it's both a
run-time and a compile time "issue". But how important is that for us? I
mean, for "production", there almost certainly would be very few cases
where someone would run ATS v2.0 and ATS v3.0 on the same box.
So, the "use" case for ATS to version the includes would be for
developers / packagers who needs to produce plugins for more than one
version. I'm not for or against "handling" that in our packaging, but I
think it's pretty reasonable that someone would either have to specify a
specific -I directive manually, or simply have a couple of VMs with
different installations. At a minimum, they would have to manually do
something to switch between include versions.
If we go the version route, I do like to have the "default" behavior.
I'm not sure we should "pollute" the top level include dir, so maybe
something like this (slightly modified from John's proposal):
/usr/local/include/ats/ats.h -> symlink to ./acive/ats.h
/usr/local/include/ats/remap_api.h -> symlink to ./active/remap.h
/usr/local/include/ats/active -> symlink to ./2.0 (or ./3.0)
/usr/local/include/ats/2.0/ats.h
/usr/local/include/ats/2.0/remap.h
/usr/local/include/ats/3.0/ats.h
/usr/local/include/ats/3.0/ats.h
(if we are dropping "api" from the InkAPI.h name, lets drop it from "remap_api" too I think? :) Once we have a finished "stub" library for linking/testing plugins, we'd have to do something similar for any .so or .a's I think (but lets not solve that problem now).
The above would make it pretty darn easy to compile for multiple
versions, just change the /active/ symlink accordingly.
-- Leif
Re: [vote] Final API file names and include dir names
Posted by John Plevyak <jp...@acm.org>.
Looking at /usr/include on my Linux system, it seems that
the vast majority of directory names are short acronyms.
And yes, most have no meaning and are just used to disambiguate
otherwise similar names (like prepending X or G before all your
public function names).
Given that I don't find 1 compelling personally as I don't
feel the need to change the world on this one :)
Regarding 3, perhaps use ats as a directory name?
Another question is how do we want to handle versions? Should we have:
ats/ats-2.0.h ?
gtk uses /usr/include/gtk-2.0
python in /usr/include/python2.5
gcc uses /usr/include/g++/4.1.2
Some folks also have a single .h which pulls in everything:
/usr/local/include/gc.h
pulls is just
#include </usr/local/include/gc/gc.h>
which pulls in everthing one needs from:
/usr/local/include/gc/*
I kind of like that.
/usr/local/include/ats.h
/usr/local/include/ats/ats.h
/usr/local/include/ats/remap_api.h
And for versions I would do:
/usr/local/include/ats/2.0/ats.h
where
/usr/local/include/ats/ats.h would include
the latest version and there might be multiple
subdirectories if we have a compatibility
layer at some point.
john
On 2/4/2010 3:16 PM, Bryan Call wrote:
> Just to clarify my position:
>
> 1. ts is a crappy name for a directory, it has no meaning and it is like
> naming a variable x or y. I believe that directories, files, variables,
> functions, etc should have meaningful names. Most people use tab
> complete or text complete by now or at least they should, so typing
> shouldn't be an issue.
> 2. "trafficserver" is already used for all other directory names
> etc/trafficserver logs/trafficserver, etc.. We should have consistency
> in the directory names.
> 3. There is one other project that uses "ts" as a directory name. I am
> not saying that there will be conflicts in the directory and file names,
> but it would be damn confusing to have two projects dump their headers
> in the same directory.
>
> Sorry if I didn't bring up these points earlier in the discussion...
>
> -Bryan
>
> On 02/04/2010 01:35 PM, Bryan Call wrote:
>> There is already code that uses the ts directory for include files
>> (simple google search, there might be others):
>>
>> http://isscvs.cern.ch/cgi-bin/viewcvs-all.cgi/TriDAS/trigger/ts/framework/src/common/CellOpInit.cc?revision=1.35&root=tridas&view=markup
>>
>>
>> [x] ts_api.h
>> [x] ${prefix}/trafficserver
>>
>> -Bryan
>>
>> On 02/03/2010 08:08 PM, Leif Hedstrom wrote:
>>> So, I think the discussions have had enough time, the consensus is
>>> definitely that we should clean up what we got. As such, we will move
>>> both include files to be in the same directory in SVN, we will rename
>>> RemapAPI.h to remap_api.h, and we will install the two header files
>>> in a well defined include directory. Two things to vote on remains
>>> (please cast votes within 72 hours):
>>>
>>>
>>> InkApi.h rename:
>>> ------------------------
>>> [ ] api.h
>>> [ ] ts_api.h
>>> [ ] sdkapi.h
>>>
>>>
>>> Include directory name
>>> ---------------------------------
>>>
>>> [ ] ${prefix}/ts
>>> [ ] ${prefix}/trafficserver
>>>
>>>
>>>
>>> Include directives would hence look like the examples below
>>> (depending on the outcome of the votes):
>>>
>>> #include <ts/remap_api.h>
>>> #include <ts/api.h> -- or --
>>> #include <ts/ts_api.h> -- or --
>>> #include <ts/sdkapi.h>
>>>
>>> -- or --
>>>
>>> #include <trafficserver/remap_api.h>
>>> #include <trafficserver/api.h> -- or --
>>> #include <trafficserver/ts_api.h> -- or --
>>> #include <trafficserver/sdkapi.h>
>>>
>>>
>>> Cheers!
>>>
>>> -- Leif
>>>
>>
>>
>
Re: [vote] Final API file names and include dir names
Posted by Bryan Call <bc...@yahoo-inc.com>.
Just to clarify my position:
1. ts is a crappy name for a directory, it has no meaning and it is like
naming a variable x or y. I believe that directories, files, variables,
functions, etc should have meaningful names. Most people use tab
complete or text complete by now or at least they should, so typing
shouldn't be an issue.
2. "trafficserver" is already used for all other directory names
etc/trafficserver logs/trafficserver, etc.. We should have consistency
in the directory names.
3. There is one other project that uses "ts" as a directory name. I am
not saying that there will be conflicts in the directory and file names,
but it would be damn confusing to have two projects dump their headers
in the same directory.
Sorry if I didn't bring up these points earlier in the discussion...
-Bryan
On 02/04/2010 01:35 PM, Bryan Call wrote:
> There is already code that uses the ts directory for include files
> (simple google search, there might be others):
>
> http://isscvs.cern.ch/cgi-bin/viewcvs-all.cgi/TriDAS/trigger/ts/framework/src/common/CellOpInit.cc?revision=1.35&root=tridas&view=markup
>
>
> [x] ts_api.h
> [x] ${prefix}/trafficserver
>
> -Bryan
>
> On 02/03/2010 08:08 PM, Leif Hedstrom wrote:
>> So, I think the discussions have had enough time, the consensus is
>> definitely that we should clean up what we got. As such, we will move
>> both include files to be in the same directory in SVN, we will rename
>> RemapAPI.h to remap_api.h, and we will install the two header files
>> in a well defined include directory. Two things to vote on remains
>> (please cast votes within 72 hours):
>>
>>
>> InkApi.h rename:
>> ------------------------
>> [ ] api.h
>> [ ] ts_api.h
>> [ ] sdkapi.h
>>
>>
>> Include directory name
>> ---------------------------------
>>
>> [ ] ${prefix}/ts
>> [ ] ${prefix}/trafficserver
>>
>>
>>
>> Include directives would hence look like the examples below
>> (depending on the outcome of the votes):
>>
>> #include <ts/remap_api.h>
>> #include <ts/api.h> -- or --
>> #include <ts/ts_api.h> -- or --
>> #include <ts/sdkapi.h>
>>
>> -- or --
>>
>> #include <trafficserver/remap_api.h>
>> #include <trafficserver/api.h> -- or --
>> #include <trafficserver/ts_api.h> -- or --
>> #include <trafficserver/sdkapi.h>
>>
>>
>> Cheers!
>>
>> -- Leif
>>
>
>
Re: [vote] Final API file names and include dir names
Posted by Leif Hedstrom <zw...@apache.org>.
On 02/04/2010 02:35 PM, Bryan Call wrote:
> There is already code that uses the ts directory for include files
> (simple google search, there might be others):
>
> http://isscvs.cern.ch/cgi-bin/viewcvs-all.cgi/TriDAS/trigger/ts/framework/src/common/CellOpInit.cc?revision=1.35&root=tridas&view=markup
So, with the discussion starting up again, I'd like to cancel my
previous call for vote, and open up the floor for discussion.
I personally think this argument above is pretty weak, the odds of this
project being installed together with Traffic Server in /ts/, and having
a naming conflicts with our files are astronomically small.
That much said, I'd also like to revoke my proposal for the api.h name
(it does become to generic together with /ts/), leaving two candidates
so far: ts_api.h and sdkapi.h.
Please discuss further, and add/remove to the proposal. I'll summarize
and send out a new request for vote in 3 days.
Cheers,
-- leif
Re: [vote] Final API file names and include dir names
Posted by Bryan Call <bc...@yahoo-inc.com>.
There is already code that uses the ts directory for include files
(simple google search, there might be others):
http://isscvs.cern.ch/cgi-bin/viewcvs-all.cgi/TriDAS/trigger/ts/framework/src/common/CellOpInit.cc?revision=1.35&root=tridas&view=markup
[x] ts_api.h
[x] ${prefix}/trafficserver
-Bryan
On 02/03/2010 08:08 PM, Leif Hedstrom wrote:
> So, I think the discussions have had enough time, the consensus is
> definitely that we should clean up what we got. As such, we will move
> both include files to be in the same directory in SVN, we will rename
> RemapAPI.h to remap_api.h, and we will install the two header files in
> a well defined include directory. Two things to vote on remains
> (please cast votes within 72 hours):
>
>
> InkApi.h rename:
> ------------------------
> [ ] api.h
> [ ] ts_api.h
> [ ] sdkapi.h
>
>
> Include directory name
> ---------------------------------
>
> [ ] ${prefix}/ts
> [ ] ${prefix}/trafficserver
>
>
>
> Include directives would hence look like the examples below (depending
> on the outcome of the votes):
>
> #include <ts/remap_api.h>
> #include <ts/api.h> -- or --
> #include <ts/ts_api.h> -- or --
> #include <ts/sdkapi.h>
>
> -- or --
>
> #include <trafficserver/remap_api.h>
> #include <trafficserver/api.h> -- or --
> #include <trafficserver/ts_api.h> -- or --
> #include <trafficserver/sdkapi.h>
>
>
> Cheers!
>
> -- Leif
>
Re: [vote] Final API file names and include dir names
Posted by George Paul <ge...@apache.org>.
InkApi.h rename:
------------------------
[ ] api.h
[X] ts_api.h
[ ] sdkapi.h
Include directory name
---------------------------------
[X] ${prefix}/include/ts
[ ] ${prefix}/include/trafficserver
-George
On 2/3/10 8:08 PM, Leif Hedstrom wrote:
> So, I think the discussions have had enough time, the consensus is
> definitely that we should clean up what we got. As such, we will move
> both include files to be in the same directory in SVN, we will rename
> RemapAPI.h to remap_api.h, and we will install the two header files in a
> well defined include directory. Two things to vote on remains (please
> cast votes within 72 hours):
>
>
> InkApi.h rename:
> ------------------------
> [ ] api.h
> [ ] ts_api.h
> [ ] sdkapi.h
>
>
> Include directory name
> ---------------------------------
>
> [ ] ${prefix}/ts
> [ ] ${prefix}/trafficserver
>
>
>
> Include directives would hence look like the examples below (depending
> on the outcome of the votes):
>
> #include <ts/remap_api.h>
> #include <ts/api.h> -- or --
> #include <ts/ts_api.h> -- or --
> #include <ts/sdkapi.h>
>
> -- or --
>
> #include <trafficserver/remap_api.h>
> #include <trafficserver/api.h> -- or --
> #include <trafficserver/ts_api.h> -- or --
> #include <trafficserver/sdkapi.h>
>
>
> Cheers!
>
> -- Leif
>