Chapter VI
- eVote for Programmers -

Source Code

Source code for all software associated with eVote(R)/Clerk 2.52 is available online at http://www.sourceforge.net.




eVote's Directory Structure

The directory structure for the sources to eVote(R)/Clerk is shown below. The directories with '*' contain source code that is compiled into eVote's mail interface.

            EVOTE_HOME_DIR/
                  |
                eVote/
                  |
   --------------------------------
   |              |               |
 data/           doc/            src/ --> makefile for "make install"
                                  |
   --------------------------------------------------------------
   |              |              |              |               |
 Clerk/        Clerklib/        demo/          mail/*         tools/
                                 |              |               |
                             eVoteui/           |               |
                                                |               |
        -----------------------------------------        ---------------------
       |            |            |          |           |        |    |   |   |
    mailman/*   majordomo/* mailui/*     message/*   filters/* utils/ |   |   |
       |            |                                                 |   |   |
        \          /                                          chiapas95/  |   |
      * only one is compiled                                         errors/  |
        into the mail interface                                          trans/
    




Source files

The source code files in this distribution are:

*** EVOTE_HOME_DIR/eVote/src:

makefile -- makefile for the entire eVote/Clerk application.  Used
            at installation time.

*** EVOTE_HOME_DIR/eVote/src/mail:
     This is where you make the executables for the mail interface.

eVote_insert.c --  has main(..) for eVote_insert
eVote_insert.h --  has a the declarations needed in this directory.  
eVote_mail.c --  has main(..) for eVote_mail  
eVote_petition.c --  has main(..) for eVote_petition
makefile --  makefile for the mail interface.

*** EVOTE_HOME_DIR/eVote/src/mail/mailman:

list.c --  functions that relate to the Mailman list server.

*** EVOTE_HOME_DIR/eVote/src/mail/majordomo:

list.c --  functions that relate to the Majordomo list server.

NOTE: Only one list.c is compiled into the mail interface.

***  EVOTE_HOME_DIR/eVote/src/mail/mailui
  The voting parts of the email interface are in here. 

confirm.c --  functions relating to the confirmation of critical messages.
do_eVote.c --  drives processing for eVote requests.  Also some initialization.
form.c --  controls a petition's form.  Functions that needs translation
  are in pet_out_xx.c files.
help.c --  runs the help facility for eVote/Majordomo
listm.c --  has functions that relate to the whole mail list.
lock.c --  has hand-written locking mechanism.  The Linux one didn't work 
  when this was written.
maildef.h --  has a few #defines that are used throughout the code.
mailui.h --  has declarations for the functions in all the *.c's in this
  directory except for signatures.c and table.cc.  Also has 
  declarations for EVOTE_HOME_DIR/eVote/src/mail/list.c And it
  has language typedefs.
makefile -- makefile for this directory
new_poll.c --  provides a new poll.
pet_out.c --   has functions for processing petitions requests from the user.
pet_out_fr.c --  These are translations of the same code. 
pet_out_es.c --
petition.c -- has petition functions that don't have strings to the user and
  don't need translation.
poll.c -- provides functions that deal with an established poll.
poll_list.c -- just lists the polls.
queriesm.c -- provide who-voted and how-voted functions.
report.c -- handles reports on petitions that are shipped to remote www pages
  via ftp.
signal.c -- just sets and receives signals.
signatures.c -- handles the signatures files for petitions.
spread.c -- makes spreadsheet-style displays of voting results.
subject.c -- massages the subject line.
table.cc -- is the only c++ module, to practice templates and operator-
 overloading. For petitions, it handles the "translation table", and decides 
 if the subject is a translation of a petition title on any petition list.
table.h --  This little header is #included into table.cc only.
text.c -- handles the storage and displaying of a poll's text.
util.c -- has some date functions and other miscellaneous things.  
voterm.c -- has the functions that relate to the individual voter.

*** EVOTE_HOME_DIR/eVote/src/mail/message
 has modules that relate to reading and writing the messages.
 It has the tokenizer that parses the mail messages.  It depends
 heavily on the filter facility: EVOTE_HOME_DIR/eVote/src/tools/filters

in_message.c -- provides a few functions that read the incoming message.
  Other functions involved in reading the incoming message are in: 
  EVOTE_HOME_DIR/eVote/src/tools/filters
makefile -- make for this directory
message.h -- has declarations for the message library.
out_message.c -- generates headers and errors and finishing output for
  the outgoing messages.
send.c -- has functions that fork and exec a new process.
token.c -- tokenizes the input buffer, buffered up in filter.c.

*** EVOTE_HOME_DIR/eVote/src/tools/filters
  has sources for various mail filters.  eVote's mail interface
  is also a mail filter and uses this code.

README --  describes the six executables in the filters directory.
angel.c --  driver for the program that watches over a protected email 
  address.  It sends unsubscribes to unwanted lists.
fence.c --  drives the program that filters mail, fencing out unwanted stuff.
filter.c --  library functions for all the filters.
filter.h --  has declarations for the filter library. 
forward.c --  forwards mail that comes into an alias adjusting the from address
  and the subject line.
makefile -- makefile for the filters in this directory.
pick.c --  drives the program that picks out a language(s) from a mail stream.
pick.h --  header for the pick filter.
puppet.c -- allows you to send mail from your home machine remotely.
shelter.c --  hides an email address and provides an alias for fencing.

*** EVOTE_HOME_DIR/eVote/src/demo
  has source for the first eVote interface.  It has "eVote", the program
  that controls The Clerk, and eVote_demo, the telnet interface.

eVote.c --  has the main for the "eVote" program that controls The Clerk.
eVote.h --  contains #defines that belong in the conference application.
eVote_demo.c --  has the main driver for the demo.  This is where you start 
  if you are making a new user interface.
eVote_io.c --  has input/output routines for the telnet interface.
makefile -- makefile for eVote_demo and eVote executables.

*** EVOTE_HOME_DIR/eVote/src/demo/eVoteui
  has the telnet user interface library.

blurbs.c --  contains text data for the demo.
command.c --  real driver for "eVote", The Clerk's interface.
conf.c --  user-interface calls that relate to whole conferences.
eVoteui.h --  has the declarations for the library.
explain.c --  drives the teacher text for the demo
explain.txt --  contains teacher text data.
input.c --  asks questions and checks answers about new polls.
item.c -- provides poll item related functions.
makefile -- makefile for this directory.
menu.c -- has the interface for the menu.
misc.c -- has a few utility functions.
poetry.c -- fake demo text.
queries.c -- menu and processing for how-voted and who-voted commands.
ui.c -- has startup functions for the demo that are not used by the
  eVote command executable.
voter.c -- has functions that deal with the individual voter.

EVOTE_HOME_DIR/eVote/src/Clerklib

The functions in Clerklib speak to The Clerk via InterProcess
Communication, using both the message facility and shared memory.  The
object files that are compiled from the sources in Clerklib are
archived into a library, Clerklib.a, for linking into the user
interface, either the demo or the mail interface, or something new.

Clerk.h  -- declarations for the interface to The Clerk, by file.
Clerkdef.h -- structure definitions and #defines
confl.c -- functions related to conferences, or email lists.
eVote_defaults.h -- hard coded system defaults, over-ridden by eVote.config
ipc_msg.c -- IPC message calls to the Clerk.
ipc_msg.h -- header for message queue functions, sent_inst and get_msg,
  which are only called by functions in Clerklib and not available to 
  user-interfaces.
ipc_shm.c -- Maintains item_info array in shared memory.
iteml.c   -- Functions to make and drop items and change the status.
makefile -- for make
maint.c   -- Functions to maintain The Clerk itself.
msgdef.h  -- #defines of IPC message strings, ITYPE definition.
mtype.c   -- two functions to make strings of ITYPE and RTYPE -- for debugging.
queriesl.c -- functions to query the data about who voted and how.
start.c -- startup functions needed by eVote and any user interface.
stats.c -- maintains the voter's statistics
voterl.c -- functions relating to the voter: voting, entering, leaving, ...

EVOTE_HOME_DIR/eVote/src/Clerk

evotedef.h  -- #defines for The Clerk -- globals variables.
  ../Clerklib/msgdef.h -- #defines for message formats.
  ../Clerklib/Clerkdef.h -- typedefs for both sides of IPC.

main.cc -- main function and other startup and maintenance things.
msgbuf.h  has only the definition of struct msgbuf

qlist.cc -- Maintains the list of outgoing message queues, one to each
qlist.h     user -- Has qlist::send to send messages a the queue
  outq.cc -- Maintains the outgoing message queue
  outq.h

inq.cc -- Maintains the single incoming message queue which receives
inq.h     instructions -- and it instantiates the instruction class:

  Classes are listed under the files where they are defined and 
    look like: <Joining>

instruct.cc  Implements base classes for the instruction hierarchy:
             <Instruction>, <NeedsQ>, <HasQ>, <MaybeQ>, and <RespondOnce>.
instruct.h
  needsq.cc  Instructions that need to establish a queue and keep it up.
    <EnterAdmin> - Entering the conference for administrative tasks
    <Entering> - A voter is entering the conference.
    <Joining> - A voter is entering the conference for the first time.
    <Leaving> - A voter is leaving the conference for now -- drop the queue.
    <LeaveAdmin> - The administrator is leaving the conference -- drops queue.
  respond1.cc - Instructions that need a queue for one reply only
    <CheckConf> - Checks the stats on the conference
    <CreateConf> - Creates a conference
    <DropConf> - Drops a conference from the system
    <DropVoter> - Drops a voter either from a particular conference or
                  all conferences.
    <Exist> - Does the conference exist?
    <Hello> - Checks that The Clerk is up and running.
    <SyncConf> - Forces the itemlist to match one that is sent in.
    <WhosIn> - Sends a list of who is in a conference.
  hasq.cc    Instructions from users that already have queues established
    <CreateItems> - Creates new voting items.
    <DropItems> - Drops items from the conference.
    <AboutItem> -  Not instantiated.
        <ChangeVStatus> - Changes the status of the vote item.
        <HowVoted> - Queries for how someone voted.
        <IRead> - Marks in the ballot that the item has been accessed.
        <IVote> - Marks the ballot with the vote -- returns old vote.
        <PullTime> - Retrieves time and offset for petition signature.
        <PushTime> - Stores time and offset for petition signature.
        <SendStamp> - Sends the time of the signature.
        <SendStats> - Sends statistics about items.
        <WhoSigned> - Sends a list of the signers of a petition.
        <WhoVoted> - Answers a query about who voted > 5 etc.
    <ChangeAction> - Changes status of the voter.
    <MidDropped> - Voter has changed to the a shared memory segment and
                   is no longer attached to the old memory id (mid).
    <Move> - Change the email address of the voter.
    <UidExist> - Checks for the existence of a user id in a conference.
  maybeq.cc  Instructions where the user may or not have a queue
    <WhoIs> - Send back an address for a voter-id.
    <WhoNum> - Sends back a voter-id number for the email address.
  noq.cc     Instructions that don't need a queue
    <DoDebug> - turns on debugging
    <DropOldQs> - Looks for useless queues to drop
    <DownPriority> - Diminishes the priority on the Clerk's process
    <Flush> - flushes the log
    <GrowConf> - Makes more space in the ballots.
    <NewExe> - Prepare to change executables.
    <NewLog> - Moves the log to a backup and opens a fresh log file.
    <Quit> - Bring down The Clerk.
    <ReorderConf> - Puts the ballots in order and deletes dead ballots.
    <UpPriority> - Increases the priority on The Clerk's process.
    <WhoDrop> - Drops an address/voter-id from the WhoList.
    <WhoSync> - Counts all the voters in conferences and corrects the
                WhoList.

conflist.cc   Keeps the list of Conferences or email lists
conflist.h

  conf.cc  Maintains a Conference - Contains a VoterList, BallotBox,
  conf.h   and ItemList.

    voterlis.cc  Maintains the list of voters in the conference
    voterlis.h
      voter.cc   Does things on the voter's behalf
      voter.h

    ballotbo.cc  Maintains the ballots for voters in the conference
    ballotbo.h
      hash.cc    Maintains a hash table for the ballots
      ballot.cc  Maintains a ballot.
      ballot.h

    itemlist.cc  Maintains the list of items in the conference
    itemlist.h
      dropord.cc  Mainstains the list of items, with temporary numbering for
                  humans.
      applist.cc  Maintains the list of items in shared memory
      applist.h   for the user interfaces
        memseg.cc  Maintains a shared memory segment
        memseg.h
memlist.cc  Maintains the list of all shared memory segments in the system
memlist.h
       item.cc  Base class for the item hierarchy -- no voting
       item.h
         itemid.cc  Item id functions
         itemid.h
       titem.cc  Tallied Item -- voting
       sitem.cc  Stamped Item -- petitions
       gitem.cc  Grouped Item -- vote on 1 of 3 etc.
         itemgrou.cc  For maintaining a group of gitems
         itemgrou.h
    grouplis.cc -- Maintains a list of all the item groups in the conference.

debug.cc -- debugging tools
debug.h

util.cc -- file handling and string utilities.
wholist.cc  -- Maintains a list of voter-id <-> email address
wholist.h

*** EVOTE_HOME_DIR/eVote/src/tools/utils
  contains some helpful tools for administrators.

deaccent.c -- filter to convert accented letters to 7 bit text
eVote_script --  You can use this script to take control of stderr from 
  Majordomo.
embed --  Utility to help get started with embedding eVote into a different
  user-interface.
ipctest.c --  Run this test to find the parameters of your ipc.
sorter.c  -- Sorts incoming mail by language and sends it on.
tryagain.c --  Crash_command for The Clerk.  When this is called from a dying
  Clerk, it behaves intelligently.
unequal.c -- Converts quoted printables to 8 bit text.
unhex.c --  A mail filter to replace hex code with ascii characters.

*** EVOTE_HOME_DIR/eVote/src/tools/chiapas95
  has a tar file with all the sources for the chiapas95 democratic
  news list project.

*** EVOTE_HOME_DIR/eVote/src/tools/errors
  has the source code developed when we were under attack for hosting
  the Zapatistas Consulta.  

*** EVOTE_HOME_DIR/eVote/src/tools/trans
  has the source code for translating strings from one human language
  to another.  Also, it has the current translations tables for eVote's
  petition interface for Italian, Spanish and French.  The French 
  translation tables have string translations for all of eVote 2.0.

README -- instructions for using the translator tool.
en_es.right -- translation table from English to Espanol.
en_fr.right -- translation table from English to French.
en_it.right -- partial translation table from English to Italian.
trans.c -- source code for the translator tool.
trans.h -- header file for the translator tool.
trans.skips -- included in compilation -- has a list of phrases that should
  not be translated.
    




Serialized Executables

Also available at http://www.sourceforge.net is a "release" directory structure for staging and building serialized executables that run on Majordomo only, for distribution without source. These executables expire automatically.

In the release directory:

README        -- instructions for making a new serialized release.
eVote.README  -- instructions for installing a serialized version.
eVote_install -- directory for making the serialized versions.

Also in this directory will appear the serialized gzipped tar files,
with expiring executables that look like:

   eVote-2.52.tar.gz.0   -- having no serial number and no expiration date.
   eVote-2.52.tar.gz.1   -- having serial number 1 and an expiration date.
   eVote-2.52.tar.gz.2   -- having serial number 2 and an expiration date.
   etc.

Installations will require one of the serialized gzipped tar files and
the eVote.README.

The release/eVote_install directory contains:

  2.52/         -- staging area for version 2.52
  install_eVote -- script for installation of serialized versions
  make_install  -- script to stage code for making serialized versions
  make_serial   -- script to make each serialized version

In the staging area release/eVote_install/2.52/, for example, the
make_install script will make:

bin/   -- directory for staging executables
eVote/ -- directory for the sources for the current release
eVote.README.latest  -- copy of the current ../../eVote.README
eVote_files  -- list of files that go into the serialized release
install_eVote.latest  -- copy of the current ../../install_eVote
make_install.latest -- copy of the current ../make_install
make_serial.latest -- copy of the current ../make_serial

To make a new version, change the version number:

*  in release/eVote_install/make_install

*  in release/eVote_install/make_serial  - Also change the expiration date in
   this script.

*  in release/eVote_install/install_eVote

*  in EVOTE_HOME_DIR/eVote/src/makefile

*  in EVOTE_HOME_DIR/eVote/src/makefile

*  in EVOTE_HOME_DIR/eVote/src/makefile

*  throughout EVOTE_HOME_DIR/eVote/doc/eVote.doc

Then, cd to eVote_install and type make_install.

The first time you'll get the message:

You need to copy eVote_files from the previous release into:
/release/eVote_install/x.xx
and then make_install again

eVote_files is a list of files that are in the release.

Do this and run it again.

Then you are ready to run make_serial.  To make an executable with
serial number 37, type this command:

make_serial 37

The eVote-2.52.tar.gz.37 file will appear in the /release directory.

Good luck!


  





Back to Table of Contents Chapter VII

Last modified: Tue Mar 4 04:18:26 EST 2003