Arnim Läuger wrote:
>> Rutger Hofman wrote:
>>> Is the path as laid out by Przemyslaw considered a good idea by
>>> the UrJtag community?
> Kolja Waschk wrote:
>> I'd like to tell at least that I personally do favor the approach
>> described by Przemyslaw Iskra. IMHO it is the right way to go.
> I'd second that. Turning the jtag shell commands into API functions
> would keep the implications low since there are not many fundamental
> changes involved. It will be just the first of a series of steps
> towards a well-featured UrJTAG library, however.
>
> My basic view on this topic is to first do the transition to liburjtag.a
> as shown in Przemyslaw's code. This includes redefining the command
> shell interface to have commands separated from API functionality. At
> the moment src/cmd/* implements shell commands AND related
> functionality, this needs to change then.
> Namespace clean-up and file renaming should happen here as well.
>
> As a result, liburjtag would expose library functions that are
> equivalent to the currently existing commands. I'd call this the
> legacy/cmd API.
As a preparation for doing the Librarification, I would like to discuss
any changes I will perform in some more detail. More messages with
deeper detail will follow...
The work performed by Przemyslaw Iskra (as from his svn) seems to have
focused mostly on using libtool, when I compare checkouts.
For starters, I propose to separate this Librarification from any other
changes, like changing the build system, adding bindings for other
languages etc. IMHO those changes are not an essential part of
Librarification: they can be done separately without problems.
Integrating them with Librarification may obfuscate the source of any
problems, and it may hold back the work because of discussions involved
:-) . Opinions?
List of proposed changes
========================
- create one liburtjag in stead of various smaller libs;
- create a public API for the library functionality; the 'shell' cmd
is just one main program that should invoke the API;
- add error handling for the public API functions;
- where appropriate, move stuff from the 'shell' cmd into the library
(while retaining all functionality for the parts database);
- clean up the name space where conflicts may arise, by adding
prefixes to:
+ global symbols
+ types
+ include file names
+ preprocessor symbols
- rename source files.
Are there other things that should be refactored, like places where the
code tree should be reorganized or whatever? Or is that best left as a
separate step?
Plan of attack
==============
svn claims it can handle file renames and merging. I am not 100%
confident that that really works. So, to be on the safe side, I would
like to await release 0.10 and then create a branch. Would the
repository need to be frozen while the Librarification is under way?
Since svn can do branch merging across file renames, that would
technically be unnecessary. And I think I will be the one who will merge
the Librarification branch into trunk when all is over. Still, large
changes on trunk would make the merge significantly more work. My
proposal: no freeze, but encourage other commits to await the merge.
How should I commit on this Librarification branch? I like to commit
frequently, even broken builds -- and sometimes that seems unavoidable
when files are renamed. This means that that branch is unusable for
other people, except for browsing. If other people do really need write
access to a Librarification branch, I would propose to create a 'stable'
Librarification branch beside my unstable working branch. FWIW, I am not
in favor of 2 branches, because of the maintenance involved.
Issues to be discussed (1)
==========================
OK, now a (first) list of issues that should be discussed before I can
even think of starting. Please, give your opinion.
What is a good project-identifying prefix?
------------------------------------------
I can think of:
- urjtag_
- jtag_
- urj_
personally (FWIW) I prefer three-letter prefixes. So, for me, do urj_.
Symbol names
------------
In my projects (FWIW) I prefix global symbols by a project prefix and
any number of appropriate module prefixes. This way, symbols from
different modules can have the same 'basename' and still be exportable.
E.g. I have mrg_acl_tag_locate(), mrg_acl_reader_locate(),
mrg_util_sort_locate(), etc etc for things that _locate(). Because of
this style, naming convention is 'inside-out': deeper submodules get
appended, and the 'basename' comes last. For UrJTAG, that might make
symbol names like urj_tap_cable_<function>().
Type names and preprocessor symbols
-----------------------------------
The changes to symbol names would also apply to type names. Besides, do
we want to orthogonize type names, e.g. by having them uniformly end in
_t, always having struct typedefs, etc?
Preprocessor symbols that we define should ideally also be
disambiguated, like #define URJ_BSBIT_INPUT i.s.o. #define BSBIT_INPUT.
FWIW, I am in favor of this change.
Coding style
------------
UrJTAG has a favorite coding style, GNU with -nut and -bli0. Lots of
files have a different coding style. What do we want?
+ retain coding style of individual files, or
+ move to a uniform coding style (run indent over the source)
Changing to a uniform coding style will make changes harder to track.
Anyhow, if it is desired, I think it is better to do this as a separate
step, outside the Librarification.
What do we do with any warnings generated by the compiler? Should I fix
any that I meet? Should we enable -Werror? FWIW, I have -Werror in my
projects because I dislike warnings :-) Any other desirable warnings
like -Wundef -Wformat -Wformat-nonliteral ...? Are we content with the C
dialect (which currently appears to be GNU C), or would we prefer -ansi
or -std=c99 or ...?
Or should I stay away from all this?
File names
----------
If we switch from multiple small libs to one liburjtag, then file names
must be unique. A quick check (find | uniq -d) shows that the following
names occur multiple times:
bsdl.c
cable.c
ChangeLog
.cvsignore
detect.c
detectflash.c
discovery.c
idcode.c
instruction.c
Makefile.am
part.c
README
readmem.c
register.c
signal.c
svf.c
svf.h
tap.c
writemem.c
By prefixing source file names with a prefix that reflects the
module(s), source file names will become unique (ignoring pathological
cases). So, that would mean: src/cmd/cable.c and src/tap/cable.c would
become src/cmd/cmd_cable.c and src/tap/tap_cable.c, or
src/cmd/urj_cmd_cable.c and src/tap/urj_tap_cable.c. Any preference?
Global API include file
-----------------------
I assume we want one global include file urjtag.h that specifies the
complete library API. It will probably #include other public include
files. Would it be a good idea to annotate the API in this top-level
include file in Doxygen style? FWIW, I like Doxygen. It forces you to
document your API and that's A Good Thing. Would we then want to
Doxygen-annotate the other include files too? That will be a major,
nonautomatable effort, which ideally would be carried out by the authors
of the respective modules.
Error handling
--------------
How should the API functions handle errors? In current cmd, an error
report is printed, and the cmd returns 1 for nonserious error or -1 for
serious error. For a library, that is unsatisfactory. A library function
should return more descriptive error status, possibly by setting
global/glocal information. I have no ideas yet of a suitable set of
errors. Opinions?
Public include file names
-------------------------
Do we want to rename all public include files too by adding a prefix, so
there is less chance of a collision with include files from other
software packages? We would have include/urj_cmd.h i.s.o. include/cmd.h,
for example. FWIW, I am in favor of this change. Opinions?
Imported libs
-------------
Are there modules that are borrowed from elsewhere, which must escape
this whole transformation? Else, we might lose the possibility to easily
pull upgrades.
Rutger
|