Index of /~lloyd/tildeProgLang/Gnumeric/latest/eg-beginner

[ICO]NameLast modifiedSizeDescription
[PARENTDIR]Parent Directory  -  
[ ]Makefile.am2017-02-21 14:03 517  
[TXT]Makefile.in2017-02-21 14:03 14K 
[TXT]functions.c2017-02-21 14:03 5.3K 
[TXT]plugin.xml.in2017-02-21 14:03 561  

.../plugins/eg-beginner/README.html

Beginner Exercise #1, adding functions to gnumeric: The directory .../plugins/eg-beginner/, and the consequent changes implied by plugins/README, are sufficient to add the new function add2numbers to gnumeric.

NB. It seems to me that it is essential to have a machine running the "unstable" (it's just a name) Debian Linux in order to build the most recent gnumeric (for version 1.2.1 as of 11/2003 at least) because of dependencies on other recent libraries.

  1. Get your copy of gumeric and untar it in a suitable directory.
    (This exercise has been checked with gnumeric-1.2.1.)
  2. Make the thing. You need to know a little(?) about configure and make:
    1. Read the INSTALL file but, if you are new to this game,...
    2. ...you may find useful starting advice in starting-with-python.html which is mostly about python but also contains general instructions on how to get going.
    or, to make an "experimental" version (as an ordinary user, not doing a system-wide installarion as root) so that it doesn't add to the src tree...
    1. mkdir <an_install_dir>  {"recommended" to be outside the src tree}
    2. cd gnum...
    3. mkdir <scratch_dir>
    4. cd <scratch_dir>
    5. ../autogen.sh --prefix=<an_install_dir>/   generally only needed once, before 1st make (or ../configure --prefix=...) {¿make distclean   may be necessary sometimes for a 2nd shot after "big" changes?}
    6. make   {can take a long time, the 1st time}
    7. make install   {might give errors about permissions on /etc}
    8. <an_install_dir>/bin/gnumeric     {runs it -- if it compiled!} 
    -|--install_dir
 |
 |--gnum'--|--...
           |
           |--plugins
           |
           |--scratch
  3. If not already there (in the main src tree), add the directory plugins/eg-beginner/ and its contents Makefile.am, functions.c, plugin.xml.in and this README.html. (Eventually several other files are automatically generated.)
  4. If not already mentioned there, make sure that eg-beginner is mentioned in a similar way to fn-date, say, in each of the files specified in plugins/README.
  5. Make gnumeric again. With luck, there will be no errors and add2numbers will be added to the list of functions.
  6. Now depending on what you really want to do... rename eg-beginner/, rewrite eg-beginner/functions.c, etc..
  7. Notes
    1. 18/11/2003: It appears that gnome-common and libtool1.4 are contradictory and cannot be both installed at the same time. [-njh]
selected directories and files
gnumeric-?.?.?/
INSTALL  
configure.in the name says it
doc/
C/ some documentation here (NB. C=>English)
developer/ some documentation; not sure of philosophy
guile-gnumeric.txt also see guile in plugins; includes a spec' of gnumeric types -- "fsbraA?|".
starting-with-python.html mostly python, but the section on installing and building gnumeric is of general use to beginners
writing-functions.sgml add2numbers toy function -- NB. for gnumeric, version 0.2. (Later: see eg-beginner/)
plugins/
Makefile.am ???
README ...don't forget to edit po/POTFILES.in, configure.in, plugins/Makefile.am
eg-beginner/ beginner test example #1, see...
README.html this page
Makefile.am  
functions.c the code for the new function(s)
plugin.xml.in ??? needs to be here for make to work, ??? it seems necessary to create it by hand ???
NB. everything(?) else in the directory is automatically generated
applix/ held up as a good example of a file- format plugin
fn-date/ held up as a good example of a "plugin containing functions"
guile/ held up as a good example of "general purpose bridge" [for] "arbitrary sheet functions" (Guile ~ Scheme), see guile* in developer/ above
po/
POTFILES.in i.e. list of source files containing translatable strings
src/
cell.h  
func.h "Function group support", eincluding e.g. struct GnmFuncDescriptor
gnumeric.h mostly <typdef _fobar fobar;>, e.g. Workbook, Sheet, Cell, GnmValue, GnmExpr, CellPos, ..., Range,...
sheet.h  
value.h mostly <typedef _foobar>, also see gnumeric.h, cell.h, sheet.h
value.c make and manipulate values, e.g. value_new_int(), ..., value_get_as_int(), etc.

Case Studies

built-in range functions, e.g. sum a range, e.g. sum(A1:B5) etc.
src/ func-builtin.c e.g. gnumeric_sum(FunctionEvalInfo *ei, GnmExprList *nodes)
/* is sum(..., .., ...) as known in gnumeric*/
return float_range_function(..., range_sum, ...)
(also see func_builtin_init near end of file)
collect.c Helpers to collect ranges of data, e.g.
GnmValue * float_range_function(..., float_range_function_t func, ...) vals=collect_floats(...); ...func(vals, n, &res);
a wrapper function for errors etc.
rangefunc.c "Functions on ranges (data sets":-) e.g.
int range_sum(gnm_float *xs, n, gnm_float *res) NB. results is last parameter! Does the real work.
value.h & value.c Also see _GnmValueRange in value.h and value_new_cellrange() in value.c
ranges and plugins
plugins/ fn-stat/functions.c Built-in statistical functions, e.g.
static GnmValue * gnumeric_linest (FunctionEvalInfo *ei, GnmValue *argv[]) {... if(... argv[0]->type != VALUE_CELLRANGE)... } /* "least squares line fit" (linear estimator) */ (VALUE_CELLRANGE is a flag def'd in value.h) NB. registered near end of file, note type.

Glossary

*.am automake files
*.in I think it stands for "input" (to the auto something process) ???
gnumeric types for functions; see guile-gnumeric.txt
f floating point (double) or int
s string (char *)
b Boolean
r range, e.g. A1:B5
a array, e.g. {1,2,3;4,5,6} is 3×2
A array or range
? any type, check value->type
  | subsequent parameters are optional

Thanks to Charles T', Jody G', Nathan H', Peter M' -- Lloyd A' 11/2003.