This document describes how to get mkevals working on either a WINDOWS machine or a UNIX (or Linux) machine.
The mkevals program produces a draft of narrative evaluations by analyzing numerical scores on a number of "items", such as examinations, quizzes or homework. It is therefore useful when student performance is primarily based on such numerical scores. The program was originally developed for use in large introductory physics courses. Some faculty in other disciplines have also found it useful.
mkevals is basically a UNIX program, and has until now been used as such. We have now created a version that runs well on WINDOWS XP, and may also work on other WINDOWS versions, so we have written this piece as a general guide, so you can get it working correctly, whether you use WINDOWS or UNIX.
In what follows, we describe first, how to install mkevals on WINDOWS, and after that, how to install the program on UNIX.
A complete description of the mkevals program may be found here.
First, a few UNIX-style packages are needed to run mkevals.
They may be obtained from
http://gnuwin32.sourceforge.net/packages/,
where you may download (for free) the following:
coreutils, while not absolutely necessary to run mkevals, is extremely useful, since it enables the use of common UNIX commands such as ls (list), rm (remove), cp (copy), mv (move), etc. Moreover, coreutils will be necessary in case you might want to compile or recompile the program from the source code, so it's a good idea to install it on your machine.
For each of the above, click on the "setup" link (chose "Complete package, except sources"). This will enable you to download the appropriate installer to your desktop. The installation process is self-evident, just use the default settings of various paths for the installation.
When you've installed these packages, it's a good idea to make sure they work. For this, open a Command Prompt window on your desktop. The mkevals program will be run from such a window, so if you're not familiar with it, now is a good time to try it out. On most Windows versions (for example, XP) the Command Prompt is called cmd.exe. (On some older versions there is also (or instead) command.com, which provides a similar (but inferior) command prompt window.)
On Windows XP, you can open a Command Prompt window with
start
--> All Programs
--> Accessories
-->
Command Prompt
.
It should look something like this:
Now maximize the Command Prompt window and then try giving the command
cd C:\
which should take you to the "root" directory C:\.
(cd \ should do the same thing.) Then try the commands
ls and ls -l and ls -F.
The second of these should provide a long listing of the contents of the directory. (Compare with the equivalent cmd.exe command dir.) The third should mark directories with an appended "/" and executables with an appended "*". Various flags may be combined. Try ls -lF or ls -tlF. Try which groff or which which. All should produce sensible results.
This completes the preparatory steps.
After you have completed the above preparatory steps, the next step is to see whether the compiled binary executable file mkevals.exe will work for you on your Windows machine.
To do this, just download the file mkevals_setup.exe to your desktop, by clicking here. Open this setup file (which is similar to the setup files used by the GnuWin32 folks) and follow the steps. It's a good idea to check the boxes that will create desktop icons for both the mkevals executable and its documentation. At the end, if you leave the box that launches the program checked, a Command Prompt window should pop up, with the command mkevals -h being given in that window.
mkevals_setup.exe will, by default, install the mkevals
executable software
in the C:\Program Files\mkevals
folder. Included will be the
executable mkevals.exe, a pair of sample files sample.new
and
sample.old
, and an uninstall executable unins000.exe. In a
sub-directory doc
will be the documentation for mkevals in
two different formats, mkevals.html
and mkevals.pdf
.
mkevals_setup.exe will also install all the source code (including
the documentation and a Makefile
) for the
program in the C:\src\mkevals
folder, in case you might want
(or need) to compile or recompile the mkevals program on your
Windows machine. It will also install a "Bourne Again" shell (bash) in
C:\bin
; this is needed in case you want or need to recompile the
program.
NOTES: (a) Running unins000 will delete everything
installed by mkevals_setup.exe, including this source code. If you
just want to uninstall the mkevals executable and its documentation,
while saving the contents of the C:\src\mkevals
folder,
give the command make uninstall from the source code directory.
(b) If you want to compile mkevals on your machine, you will need an
appropriate C++ compiler. See the section below entitled
How to compile mkevals on Windows.
If the executable mkevals.exe works in the final step of the
installation (where the program is launched),
what you see will probably look something like this, which is the
display of a brief "help" file that summarizes the usage of the
mkevals program, including all possible options:
Note the weird character strings, which are ansi.sys character sequences
that are intended to display a few words in green color. For obscure
reasons, the usual Windows distributions do not ship with the
ansi.sys driver enabled, but if you'd like to see the green words,
it is easy to enable the ansi.sys driver. Here's how to do it
(although this step is not essential for the program to work):
If you have Windows NT, or 2000 or XP: (a) Use a convenient editor
(notepad, e.g.) to edit the file CONFIG.NT
by adding this single
line at the end of the file:
DEVICE=%systemroot%\SYSTEM32\ANSI.SYS
(b) Save CONFIG.NT
, and (c) log out and log in again to cause the added line
to take effect.
If you have Windows 95, or 98 or DOS: (a) Find out where the file
ANSI.SYS
exists on your system; (b) edit the file
CONFIG.SYS
(usually found in the WINDOWS
folder) to add
the line
DEVICE=<path to ANSI.SYS>\ANSI.SYS
where "<path to ANSI.SYS>" is what you found from step (a);
(c) Save CONFIG.SYS
, and (d) log out and log in again to cause
the added line to take effect.
If you've enabled your ansi.sys driver, here's what a launch of the
program should display:
If everything works so far (with or without the green words), try giving the command
mkevals sample.new
This should draft evaluations for the six students in the sample file
provided with the distribution, and something like the following is what
you should see appearing on the screen:
If this works, you might try exercising various options, for example, by
giving the command
mkevals -purd sample.new
You should also find that the command
mkevals sample.old
will exit with an error message, but that the command
mkevals -o sample.old
will work correctly.
The program will exit with an error message if either the which or the sed command is not found on your system; if this is the case, you may not have completed the Preparatory steps for Windows, described above.
In case none of the above works, or if it does work, but you would like to change the wording of phrases used in the evaluations (as described in the description of the program), you might try compiling the source code on your machine, as described in the following section.
First, to compile the mkevals program, you will need an appropriate C++ compiler installed on your machine. DJGPP is well-maintained, is free, and works well. (We used DJGPP on a Windows XP machine to create the executable file mkevals.exe.)
To download DJGPP, go to
http://www.delorie.com/djgpp/zip-picker.html, specify your
operating system, check the C and C++ boxes and the RHIDE box.
You will want to select (the default) "Build and run programs with
DJGPP".
You probably won't need the GNU debugger, nor any of the Extra Stuff.
Then click on the "Tell me which files I need" button, which will take
you to a page that lists the files to be downloaded, and provides good
guidance for installing DJGPP on your machine. It is
easy to install DJGPP on Windows. The documentation is clear.
It is not a large package--around 20 MB. It comes with a built in
"Gnu Make
" program so you won't need to worry about
whether or not make exists on your system.
Second, assuming you have already downloaded the file
mkevals_setup.exe
and have run it to install all the components
of the mkevals program, change to the directory containing the
source code for mkevals:
cd C:\src\mkevals
Then try giving the command make. If the DJGPP compiler is in your "Path" (which it should be if you have followed the instructions from the DJGPP site carefully), you should see the various source code pieces being compiled, ending up with the creation of the executable mkevals.exe in this directory.
Third, test your newly created executable by giving the commands
mkevals -h, and then mkevals sample.new
, as described
above. (The sample files
sample.old
and sample.new
are included with the source
code, and should be present in this directory.)
Finally, if your test is successful, try giving the command
make install. If this works, you should find that
the executable mkevals.exe is present in the
C:\Program Files\mkevals\
folder, and that the
documentation (the files mkevals.html
and mkevals.pdf
)
is present in the C:\Program Files\mkevals\doc\
folder.
Should you want to uninstall both the executable mkevals and the accompanying documentation, the command make uninstall should accomplish this.
The command make clean will remove the executable and all the object files (the files that were produced by make), and the command make distclean will restore the source code directory to its original condition. You may see some error messages resulting from these commands, but they seem to work anyway.
If you're on a UNIX machine, the process is straightforward, with no preliminary steps required. Since various UNIX systems have various architectures, we have not created any ready-to-use executables for UNIX or Linux. However it is very easy to compile the source code on a UNIX type machine. (This has been tested on a few UNIX machines.)
Just download to some convenient directory
(for example, a directory labeled src/mkevals
) the tarred
and compressed file of source code by clicking on this link:
http://maxwell.ucsc.edu/~drip/programs/mkevals/mkevals-2.3.tar.gz.
Then uncompress it with gunzip mkevals-2.3.tar.gz and extract
the contents with tar xvf mkevals-2.3.tar. (On Linux systems
this may be done in a single step: tar xzvf mkevals-2.3.tar.gz.)
This will create the sub directory mkevals-2.3
, so cd
to this directory and follow the instructions in the README
file
contained therein. Typically you will give the commands make
and, after all compiling is completed, mkevals -h
(or mkevals sample.new), and if those commands work, try
the command make install.
Once you have the mkevals program running, the next step is to use it to create some narrative evaluations. For this, you will need a good text editor. While text editors that are commonly used on Windows machines will work, you might consider trying out Gvim. It is my editor of choice. I use it for anything that requires writing--whether it's a letter to a friend or an email message or computer code or an html file. To try it out, go to http://www.vim.org/, download to your desktop the self-installing executable gvim63.exe, open it and install gvim on your Windows machine.
Essentially everything I know about Windows machines has been learned during the past few weeks, while I've been trying out (on a Dell Notebook running Windows XP) the various procedures described in this document. Much of the above is therefore arrived at by trial and error (lots of error). I have also received many generous words of wisdom from a few friends (Al Kelley, Michael Beeson, Roger Anderson) who are more knowledgeable than I am about how to make things work on Windows. Kees Zeelenberg was helpful in pointing me to Jordan Russell's Inno Setup software.
There are surely things that won't work the way I've described them. If you have suggestions for improvement I would very much welcome them. Just email me at drip@ucsc.edu.
Peter Scott