WWWWWW

Current Directory: /home/.cpan/build/Curses-1.45-0
Viewing File: /home/.cpan/build/Curses-1.45-0/MAINTENANCE
These are notes for the maintainer.

Steps to release:

  - Update ChangeLog file with description of new stuff and release date.

  - Update version number in Curses.pm (search for VERSION).

  - Test the build:

    make realclean
    Set up environment variables, c-config.h if required.
    perl Makefile.PL PANELS MENUS FORMS
    make
    perl -Mblib -MCurses -e1
    perl demo

  - Make a tarball:

    $ make dist
    $ mv Curses-1.33.tar.gz /tmp/

  - Upload via pause.perl.org.  Use "upload a file to CPAN" link.  You have to
    login to make that link appear.  PAUSE gives you various options for
    uploading, tells you how to follow the progress of the uploading and
    indexing, and sends you emails about it.

    Or do:

       $ cpan-upload-http -verbose -user ... -mailto ... \
         /tmp/Curses-1.33.tar.gz
       (Get cpan-upload-http from CPAN)

    It goes into CPAN in the directory belonging to the user who uploaded it.

  - PAUSE will automatically extract the README file from the tarball
    and install it as e.g. Curses-1.33.readme

  - PAUSE will open the tarball automatically and index the packages it finds
    in there by name (Curses::Window, Curses::Screen, etc.).


For Bryan's Rhino test system:

  Copy hints/c-linux.ncurses.h as c-config.h and edit it
  to say #include "/usr/include/form.h" instead of <form.h>


GEN
---

The package is designed to have all the distributed code files
(Curses.pm, CursesFun.c, etc.) generated by the programs in gen.tar .
This is supposed to handle the myriad Ncurses functions with less
tedium than manually editing the files.

However, Bryan doesn't know how the Gen stuff works, so he has been
making the small updates necessary directly to the distributed files.
But the changes are modest, so it should be possible some day to
generate new files, diff to see what changed, and put those changes
into the Gen programs.

Originally, what is in gen.tar was a directory named 'gen' in the Curses
package on CPAN, and CPAN unfortunately indexes the Perl modules in there as
public modules.  And because make.Curses.pm contains the perldoc stuff for
Curses.pm, people have even been misled into using that unmaintained file
for documentation of the functions in Curses.pm.

Since I don't know how to stop CPAN from doing that, I solved that problem
by tarring up the directory.


ppport.h
--------

You generate this by running the function Devel::PPPort::WriteFile().

There shouldn't be any need to generate a new one unless there are
updates to the Devel::PPPort package.

A comment in ppport.h says it was generated by Perl 5.006002.  That's
a lie.


HOW SYMBOL EXISTENCE DETECTION WORKS
------------------------------------

Part of 'make' is determining which Curses functions, etc. exist in the
target system's Curses library.

It runs the program 'testsyms' to do this.

'testsyms' is hardcoded to take the file 'list.syms' as input.  That file
lists the symbols for which to test.

'testsyms' does a test compile, and if the compile fails, assumes it is
because the symbol for which it was testing is not in the Curses library.
The program it compiles is one of the following, depending upon what kind of
symbol 'list.syms' says it is:

  testsym.c
  testint.c
  testtyp.c

The output of 'testsyms' is hardcoded to 'CursesDef.h'.  Each line of that
looks like

#define C_ADDCH                 /* Does function 'addch' exist?              */

or

#undef  C_ADDCH                 /* Does function 'addch' exist?              */

depending on whether 'testsyms' found the symbol to exist.

THERE IS A SPECIAL CASE for "w" symbols.  Where the symbol starts with "w"
(e.g. "waddch"), the C_ macro name in CursesDef.h omits the "w"
(e.g. "C_ADDCH").

Curses.c #includes CursesDef.h and subsequently #includes CursesFun.c
CursesFun.c uses the definition from CursesDef.h of C_ADDCH to decide whether
to build into the Perl module a function for 'addch'.  CursesFun.c is a long
file with a section for every Curses function that we know, defining
a Perl XS function for it such as 'XS_Curses_addch'.

N.B. CursesFun.c get #included by Curses.c.  It cannot be compiled itself.

Curses.c also includes CursesBoot.c, which contains a line for every
function we know about and binds the Perl function (e.g. Curses::addch)
to the C XS function (e.g. 'XS_Curses_addch').

In some cases,
F1l3 Manager
