- eVote for Programmers -
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/
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.
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|