libclc: status

Some thought that a clc lib was a good idea, others disagreed. Not a big
suprise on comp.lang.c ;-) Let us start the subject line with "libclc:"
so that those of you not interested in libclc easily can filter the topic.

I have, since yesterday, applied for a project named libclc on
sourceforge. It will take a couple of business days to process the
request, I expect a positive answer early next week. LGPL was chosen as
licence, BTW. IIRC the licence terms can be changed later on sourceforge.

Even some code has been posted, and this raises some issues which is
important to get right early in the project. I'll use Dan Pops
clc_strdup() as template for my questions. Here is a copy of the posted
code:

> #include <string.h>
>
> char *clc_strdup(const char * /* restrict */ s)
> {
> size_t size = strlen(s) + 1;
> char *p = malloc(size);
> if (p != NULL) memcpy(p, s, size);
> return p;
> }

And now for the questions:

q1: Do we need clc_strdup()? The real question is more like: How do we
decide what goes into libclc?

q1.1: If a function has its place in libclc, where do we put it? Still
using clc_strdup as an example, is it a string function or a memory
function?

q2: Regarding e.g. restrict, how do we handle different versions of C?

q3: The code above doesn't compile(sorry, Dan), as stdlib.h is missing.
How do we handle those kind of situations?

q4: copyright. Who has the copyright to clc_strdup? Not a big issue for
trivial functions, but someone may want to retain copyright for other
things. I suggest that the person who first posts the code has the
copyright to that code.

q5: Documentation. How should clc_strdup() be documented?
Other questions or answers?

Now for some solutions ;-)
I have created a very small library with the name libclc.a and added
clc_strdup() to it. It is available for download here:
http://highlander.metasystems.no:81/libclc-0.1.tar

Note that
- The tar file unpacks to current directory
- The makefile is extremely simple.
Both issues will be addressed when we have decided on a build system.

I have compiled the source code on three different platforms and
(suprise) it build perfectly ;-)

Please have a look at the code to see if my solutions to a few of the
questions above are OK. The issues are:
- C versions. I used a common header file, clc_settings.h, which defines
RESTRICT to different version depending on the C version used.
- Copyright.
- Documentation.
- Build system.
- versioning of libclc.
- clc header files. I created a header file named clc_string.h and put
clc_strdup declaration there, since strdup() was found in string.h on my
machine.
- # of source files. I created one file, clc_strdup.c, for the function.

Thanks again for all replies. My apologies for not responding to all the
different subthreads.

Keep the code coming ;-)
Bjørn

Netiquette question: Should replies' subject lines read "Re: libclc: ..."
or "libclc: Re: ..."? (I think my newsreader breaks threads when I
answer them, anyway; sorry!)

For Dan: The 'restrict' keyword doesn't add anything to this function,
right? Not only isn't the behavior changed, there's no opportunity for
optimization either (since no other pointers *can* change the value of
s's associated array). So do you advocate using "restrict" (in C99)
whenever possible, like 'const', or only when it makes optimization
possible, like 'register'? (I expect the next version of C will see
'restrict' go the way of 'register' -- outstripped by new compiler
technology.)

For others: I was initially worried that the legendary six-significant-
initial-characters implementation would make trouble for clc_*, but I see
that the minimum limit has been extended to 63 significant initial
characters in C99. What was it in C90?

That is the question, yes.

Since the C memory functions (mem*) live in <string.h> anyway, this is
moot.

#if __STDC_VERSION__ == 199901L.138
#define RESTRICT restrict
#else
#define RESTRICT
#endif

Fix the errors, of course! In this particular case, just replace NULL
with 0.

Consistently.

> Other questions or answers?

What exactly is the point of this library again? You're trying to
make a library of commonly-wanted extensions to the standard library
such as strdup(), but *not* to re-implement the existing library,
right? I think so, but I wasn't sure.

> (surprise) it build perfectly ;-)

I would suggest using the standard header names (e.g., "string.h"), in
a separate directory. For example,

#include "clc/string.h"

I'm almost certain the Standard allows this, and it will let people on
8.3 file systems use your code without modification (which is the point
of the whole exercise, right?).

That is what I would do.

-Arthur

Oops! I missed the call to malloc(). So I guess you'd have to add
#include <stdlib.h>
Just as easy a fix!

-Arthur

#if __STDC_VERSION__ < 199901L
#define restrict
#endif

In *any* Open Source project you should *always* state that code
contributions are a non-exclusive grant for the maintainer to do *anything*
they want with the code. No, that's not a conflictory statement. The
"anything" part is held in check by the "non exclusive" part. Think of it
as "anything except deny the contributor credit or prevent the contributor
from re-licensing his code in any manner he sees fit (excepting of course
that he can no longer deny the code to you)". Ummm... yikes... recursive
copyright priveleges... brain overflow. BRAIN EXCEPTION, but I think you
get it.

IANAL, but I believe that in practice if you specify a "non-exclusive grant
to use in any manner I see fit", people who need to know what that means,
will know.

Making some statement like that up front prevents you from having to track
down every contributor if you ever decide a license change is needed.

--$teve

Whatever the people working on it can agree on.
Not that that helps any.

My suggestion (just posted in the original libclc thread) is to call
something simple like this a `tools' function, and put its prototype in,
say, "clc_tools.h".

This doesn't really address the general question, though, and my
suggestion there is to group them according to utility - a function
that allocates memory and does something useful with <foo> should
probably go in the same place as other functions that work with <foo>.
Anything that's not too complicated and gets used in a bunch of different
places should go in the general tools collection. I'm putting clc_strdup
in the second category, but it could also sensibly be put with string
handling functions.

I would say use the common subset of C99 and C90 wherever reasonable.
Things like restrict that are useful but neither strictly necessary nor
in both C99 and C90 can be handled with a header that checks the version
and defines something like RESTRICT (or even CLC_RESTRICT) as appropriate.

The code should #include anything it needs (<stdlib.h> and <string.h>
for Dan's clc_strdup, for example). The header should also be completely
self-contained, but that should be accomplished wherever reasonable by
having stuff it needs declared there (with appropriate guards for if
it's already defined) rather than by #including another complete header
(the prototype of Dan's clc_strdup can stand on its own without anything
(except possibly "clc_cversion" or wherever RESTRICT is defined),
for example).

This might be difficult to do in practice. Good ways to do it might
be another good question.

Hmm... I'd say that copyright goes to the original author of the code,
the current maintainer, or both. (There's no good reason to have,
f'rexample, string handling code written by one person and logging code
written by another under the same copyright, if the only thing they have
in common is both being in libclc.) If there's a separate compilation
copyright (which may or may not be reasonable), that goes to the person
who's responsible for getting everything together (which looks like you).

Two different ways:
For library users - exactly what you give it, what it gives you, and
what it does with it in between. Not too long but detailed enough to
reimplement the function based only on the interface without breaking
code that uses it.
e.g.:
char *clc_strdup(const char * RESTRICT str)
Uses malloc to get memory to copy string pointed to by str into.
Returns pointer to malloc'd memory with copy of string, or NULL
on memory allocation failure.
For library maintainers - the interface it's written to (as above),
plus justifications for design decisions (e.g. Dan's decision to invoke
undefined behavior if str is null, since standard library string functions
also do, instead of returning NULL which should be reserved for memory
allocation failure) and explanation of anything interesting or non-obvious
the function does (not much to pull out as an example here).

dave

--
Dave Vandervies dj3v...@calum.csclub.uwaterloo.ca
Hey, Eric's hogging all the paranoia. He must be up to something.
Leave Me Alone too.
--Brian B. Rodenborn in comp.lang.c

Bjørn

This just makes the problem worse: Prior to C99, both
`restrict' and `RESTRICT' were available as perfectly legal
identifiers for the programmer's use. C99 took `restrict'
away; the above definition appropriates `RESTRICT'. (Also,
the #if should be written so as to do the Right Thing when
future revisions of the Standard come along; this can't be
achieved in perfection because it's impossible to be sure
what future revisions will do, but one should at least try.)

A compromise might be to name the macro CLC_RESTRICT,
with the idea that a libclc user would probably avoid inventing
identifiers beginning with cee ell cee underscore. A drawback
is that CLC_RESTRICT really ought to be an "internal" macro,
not part of the externally-visible API; perhaps it should be
#undef'ed at the end of libclc.h.

Still another alternative might be

#if __STDC_VERSION__ < 199901L
#define restrict /* nothing */
#endif
int clc_foo(restrict void *, const restrict void *);
...
#undef restrict

... but this is just as intrusive as C99's theft of `restrict'.
Perhaps someone can come up with a better solution, but the
only way I can think of to use `restrict' properly with C99
while not misappropriating C90 names is

#if __STDC_VERSION__ < 199901L
int clc_foo(void *, const void *);
#else
int clc_foo(restrict void *, const restrict void *);
#endif

... or equally ugly variations on the same theme.

--
Eric....@sun.com

This is the privilege of the project maintainer, just as deciding what
goes into the FAQ is the privilege of the FAQ maintainer.

I suggest a single header for the whole project: "clc.h" and have each
function name prefixed by "clc_" and each macro name by "CLC_". So,
no need to worry about excessive name space pollution after including
"clc.h".

BTW, "clc.h" should include <stddef.h>, to get the definition of size_t,
for the function prototypes needing it.

Put the following

#if !defined __STDC_VERSION__ || __STDC_VERSION__ < 199901L
#define CLC_RESTRICT
#else
#define CLC_RESTRICT restrict
#endif

near the beginning of "clc.h" and use CLC_RESTRICT everywhere. I really
don't like it, but it's the only robust and simple solution (short of
simply ignoring "restrict" in the interface and implementation of the
library functions).

No other C99 keywords should raise similar problems.

Simply fix the code, if the fix is obvious. Otherwise, follow the
subthread started by the bug ;-)

Couldn't care less. Those that do, should insert a copyright notice in
a comment, at the beginning of their code.

It's already documented by Unix man pages and the SUS standard. Just
drop the bit about setting errno to ENOMEM in case of failure, because we
cannot do that.

Given the nature of the project, we should not have a build system.
The code should compile on *any* system with a reasonable, conforming
implementation and have build procedures for as many platforms as people
would want/care to contribute. Of course, you'll have to maintain all
of them, when a new function is added to the library ;-)

clc_settings.h is wrong:

1. One header should be enough for the whole library. No need for
gratuitous complexity in this area. If needed by certain functions,
another header might be considered, to be used by the implementors
of the library, but not by its users. Even then, the same thing can
be achieved in "clc.h", in a section protected by the
CLC_IMPLEMENTATION_MODE macro. The functions needing it, instead
of including "clc_internal.h" would define CLC_IMPLEMENTATION_MODE
before including "clc.h".

2.
#ifndef __STDC_VERSION__
# define RESTRICT
#elif __STDC_VERSION__ == 199901L
# define RESTRICT restrict
#endif

is wrong, for two reasons:

a. RESTRICT is an intrusion into the program name space. Big no-no.

b. __STDC_VERSION__ is defined by C95 with the value 199409L. In this
case, you don't define RESTRICT at all. Ditto for future versions
of the C standard. Basically, the == operator should never be
used with __STDC_VERSION__, it's even worse than in the case of
floating point operands ;-)

Dan
--
Dan Pop
DESY Zeuthen, RZ group
Email: Dan...@ifh.de

This will break any C89 program using the "restrict" identifier.

The C99 standard library uses it everywhere possible. And I didn't
use it at all in my code ;-)

Nope: restrict doesn't ask the compiler to do anything, it is passing it
a hint. A hint that no new compiler technology can provide, in the case
of a function with the following interface:

void foo(char *d, char *s);

Six monocase. However, due to namespace issues, we have to ignore any
hypothetical C89 implementations for the PDP-11 under DEC operating
systems :-)

#ifdef restrict
#error -- another module uses the C99 keyword "restrict" as an identifier.
Do a global search and replace.
#endif

--$teve

Not for, e.g., strlen(), which was my point. If you're only passing
the function one pointer, there's no optimization benefit to including
'restrict'. So... to restrict or not to restrict?

:-)

On the contrary -- it can, if the function is used in the following
complete program:

% cat future.c
#include <stdlib.h>
#include <string.h>

{ strcpy(d, s); }

int main()
{ foo(malloc(4), "foo"); }

% futurecc --aggressive-optimization -o future future.cc
(Debug: 'char *d' made 'restrict' in function foo, line 3)
(Debug: 'char *s' made 'restrict' in function foo, line 3)
(Warning: memory leak in call to 'malloc', line 7)
%

Doesn't matter whether the 'restrict' keyword is used or not -- the
compiler is free to optimize at will, since it has perfect information.
Just like with the use of the 'register' keyword, except that 'register'
places some restrictions on the programmer (registers have no address,
e.g). This wouldn't work if the compiler didn't control the linker,
too, of course...

I should have made it clear that I'm talking about the Future with a
capital F. ;-)

-Arthur

Oh crap. You'r right... that only fixes the problem if they #defined
restrict, which is unlikely. Maybe we just need to advise people to do a
global search and replace on C99 keywords...

--$teve

I'd say the maintainer (you) has the final say. When in doubt, ask
here. The bigger issue I suspect will be with perfectly useful and valid
functions that also happen to be very similar to some other perfectly useful
and valid function. As an example, I know of a few different variations on
fgets() that have been written that have similar but not quite identical
goals in mind. It seems to me that it would be confusing to include more
than one of these, but deciding which makes the grade and which does not
will probably not be simple.

I'd also suggest that documentation should be thorough and accurate, and
both the documentation and the code should be able to survive a review here.

That I think depends on the volume of code that becomes part of libclc.
If it turns out to be a significant number of functions surving a variety of
purposes then you'll have to make a judgement call. But if it's small I'd
do what Dan said and lump it all together.

I like the idea that someone else posted about "clc/string.h" Again,
this is assuming there really is a need to divide things up into separate
headers, and also assuming that such a naming is allowed by the standard.

Absolutely.

FAQ? What have I done? :-)

clc_ and CLC_ are fine, I have to address the header file structure in a
separate post...

OK

OK. I will fix that.

Good point. Others ($teve) mentioned other important legal issues, and
IIRC sourceforge had some click-through agreement regarding copyright as
well.

The rule is therefore: If you want copyright, submit the code with the
proper copyright notice.

I was a bit vague here, sorry.
What I meant was: Who does it, what guidelines apply, which tools should
we use, what kind of format should be used, and so on. Any ideas? Is
that decided by the maintainer as well? I'd prefer some feedback here,
to avoid "scaring" potiential contributors by having too rigorous rules.

I tend to use Doxygen with Javadoc tags and document the interface in
the header file. This usually creates huge headers, which wouldn't work
too well with only one header, clc.h.

Can do, just send me the hardware, start with a Sharp Zaurus :-)

The code should build, as you said, on any system.
cc -c *.c; ar crus libclc.a *.o
is basically all that's needed. It would be nice though to have some
kind of build system, esp. for using strict compiler flags on different
compilers.

I prefer to use gcc, and then use -Wall -ansi -pedantic -Werror -W
and -std=c99 for later versions of gcc. Most other compilers chokes on
that.

I also love to *use* autotools for stuff like make dist, check,
distcheck, versioning. I don't care too much for writing the input
scripts though...

There are other issues as well, I'll save them for later :-)

OK. I'll implement that asap. I'll also add a licence and a proper
disclaimer.

Thanks.
Bjørn

IANAL, but I think you have some misunderstanding how copyright works.

You cannot `want' copyright, or rather you cannot *not* want copyright.
Everything you write is automatically copyrighted by you; contrary to
popular belief, neither a copyright notice or a registration with some
copyright office is required to obtain copyright to a work you create.

The absence of a copyright and license notice in some piece of code does not
mean it's not copyrighted, it means anybody who obtains/downloads said code
has no right to do anything with it except for those small number of rights
explicitly granted by copyright law. I think putting such a piece of code on
Sourceforge would contradict their policy that everything they host must be
``open source''.

In some countries (e.g. USA) you can waive your rights as copyright holder
by explicitly putting a work in the public domain, and stating in the source
code that you do so. Such a work is then in fact not copyrighted. Many other
countries (e.g. EU) have no equivalent of this, therefore I recommend
against such a practice in an international project.

In some contries (e.g. USA) you can assign all your rights as copyright
holder to another person/entity, in others (e.g. EU) you can assign only
some of them. For example, in Germany authorship grants you ``Urheber-
rechte'' (``creator's rights'') and ``Nutzungsrechte'' (``rights of
usage''). Only the latter can be assigned.

Finally, while I have stated all of the above to the best of my knowledge,
you should take off-topic advise with the usual suspicion.

Martin

And what I meant was that we should "steal" as much documentation as
possible, when replicating the functionality of existing stuff.

No way. The header should be as "clean" as possible.

Each function should have a concise description, using the ones from the
standard as a model. An ordinary text editor should be the only tool
needed.

It doesn't matter. If you know that the code compiles cleanly with your
mix of options (you should add -O, BTW), the build procedure only
requires the -c compiler option (or its equivalent on non-Unix
implementations).

Actually, the situation where `restrict' is already
defined as a macro is the only one that causes trouble.
Other uses of `restrict' as ordinary identifiers can be
handled cleanly:

/* libclc.h */
#ifdef restrict
#error "You lose!"
#endif
#if __STCD_VERSION__ < 199901L
#define restrict /* nil */
#endif
int clc_foo (restrict void *, const restrict void *);
...
#undef restrict /* the crucial piece */
/* end of libclc.h */

The point is that within libclc.h itself any appearances
of `restrict' have been put there by the libclc.h authors;
they don't clash with anything in the including file -- so
long as libclc.h's definition is "taken away" when no longer
needed, and so long as the includer hasn't actually defined
a macro named `restrict'.

Even this problem could be handled if there were a means
to "save off" a macro definition and restore it later on:

#pushdef restrict /* save old definition, if any */
#if __STDC_VERSION__ < 199901L
#define restrict /* nil */
#else
#undef restrict /* or maybe #pushdef does this */
#endif
int clc_foo (restrict void *, const restrict void *);
...
#popdef restrict /* restore old defn or non-defn */

Might be more trouble than it's worth, though, since it only
solves a small part of the name-collision problem within C.

--
Eric....@sun.com

Why did you choose LGPL rather than GPL? Sure, if contributors are
supported by companies who want LGPL rather than GPL, or if
contributors want to use LGPL in order to use it with propriety code,
LGPL would be better. But otherwise, why not chose GPL?

GPL was not chosen, since that would limit the usage of libclc to GPL'ed
programs (AFAIK). This is a serious drawback IMHO, since libclc is meant
to be a library which you always should be able to use, regardless of
other licenses.

LGPL was chosen over BSD mainly to keep submissions, contributions and
changes available to all. IANAL, but it seems to be a good choice for
now. LGPL v. BSD license is not a big issue to me, usability and
availability is. If LGPL limits usability, I guess we must change the
license to BSD?

HTH
Bjørn

Excellent idea.

You can dual-license it, so it is availble to users under their choice
of either.

- Kevin.

> (...)

The contributor. For one thing, anything else is probably a losing
battle. For another, if someone else studies the code and writes down
what it does, he may end up documenting bugs as if they were features.
Of course, if you _really_ want some code whose contributor won't cough
up documentation, you can always deviate from the rule.

I suggest the subset of Texinfo which is supported by emacs-19, and
to provide generated info- and html-files as well in the library
distribution.

I think so.

You can allow contributors who feel uncomfortable with the chosen
format to write plain textfiles. Others can convert them later.

I like -Wfloat-equal -Wshadow -Wbad-function-cast -Wcast-qual
-Wmissing-prototypes too, usually without -Werror.

--
Hallvard

Or more simply, if they won't document it, you reject it and
either drop the interface or get it from another contributor
who will play ball.

I suggest a format that is cross-platform portable. Something
like HTML for the web, PDF or Postscript for "pretty docs" and
perhaps plain text.

I like the idea of using a lot of different compilers to test
with on as many platforms as possible. That is the point right?

--
Randy Howard
remove the obvious bits from my address to reply.

These are bad formats for the source text, though. For that we need a
format which can be used to _generate_ HTML, PostScript and whatnot.
Maybe Textinfo. Maybe Perl's POD format. I don't know.

(And don't say HTML is an OK source text format. A lot of people - and
even many HTML generators - produce very bad HTML.)

Yup. When you have other compilers.

--
Hallvard