Vpac Howto         Vpac(Vim-Perl-Asm-C/C++)           Vpac A Users Guide
------------------------------------------------------------------------

	Now you can edit compile/assemble/debug and run a program
	without ever having to leave the Vim window.

	Filename Extensions Vpac Understands:

	[.pl .pm. .c .C .cpp .cc .CPP .c++ .asm .s .S .o .h .inc .mac]

	Any file with the above [.ext] will work with Vpac
	
WHAT IT DOES:
^^^^^^^^^^^^^

    It allows you to load, edit, build, debug and run any of the above
    program file types all in a single Vim session.
    You will need to have installed and running nasm, ald, perl, gcc,
    g++ and gdb to make full use of all the vpac features. RedHat ver 9
	comes with nasm,perl,gcc,g++ and gdb. Links to the ald debugger can
	be found on the nasm homepage.
    vpac acts like  a global workspace allowing you to program in any subdir
    of your $HOME account, it automatically selects the build options to
	suit your current project.
    All configuration options are kept in the $HOME/etc directory. Thus 
	it becomes quite easy to change configurations.


THE FUNCTION KEYS:
^^^^^^^^^^^^^^^^^^
[F12] Key: Debug mode will load up your program in gdb,perldb or ald
	   depending on the name of the file you are working on. In assembly
	   mode, you can use the [F3] key to switch between gdb and ald
	   debuggers.

[F11] Key: Runs the completed program in the Vim window. Using the [F3]
	   key you can enter command line arguments to the program. 

[F10] Key: Compile/Assembly/Test in c c++ asm or perl. Automatically 
	   selects the correct compiler/assembler/interpreter all dependant
	   on the filename entered. Any errors are placed in the error 
	   window Vim (Quickfix). Using the [F3] key enables you to compile
	   several files together to build a project. See the example below
	   in this document.

[F9] Key: Save the current file. Note the F10 key will also autosave your 
	  work prior to compiling. 

[F8] Key:  Display compile-link options. Used in conjunction with the [F10]
	  key. It works in a similar fashion to the "make -n" option. Where it
	  will display but not execute the compile-link options. Like "make" if
	  the files in question are upto date then there is no output. [F8] ON
	  means display options. [F8] OFF means normal build/compile. [F8] is
	  also used to switch debuggers whilst in assembly language mode.

[F7] Key: Close the Quickfix error window.

[F6] Key: Activate(open) the Quickfix error window.

[F5] Key: Scroll down the errors in the Quickfix window.

[F4] Key: Scroll up the errors in the Quickfix window. Asciiz decimal and
	  Hex values at the current cursor position are displayed in the status
	  bar during Quickfix operations.

[F3] Key: Toggle the command line arguments On or Off. Used in 
	  conjunction with the [F10] [F11] and [F12] function keys.
NOTE: In Perl mode the 'Enter Build Files' option is disabled. 	  

[F2] Key: Exit(quit) Vim without saving your work. Use the [F9]key to save.

[F1] Key: Not used by the Vpac programs. [Normal Vim Help]

ADDITIONAL KEYS:
^^^^^^^^^^^^^^^^
			KEYS FOR COMMENTING AND UNCOMMENTING CODE
	Some times you need to comment out some lines of code. This usually
	happens whilst testing. The [Ctrl X-Y] keys have been set up to make
	this task easier. One of the Vpac executables called vpacm (stands for
	Vim Package Comments)which sets up the key mappings in the .vimrc file.
	
			 vpacm filetype.c        maps to /*                 */
			 vpacm filetype.cc       maps to //
			 vpacm filetype.asm      maps to ;;;
			 vpacm filetype.pl       maps to ##
				 
	Vpacm reads the .ext from the filename and sets the apropriate mappings
	in the Ctrl-X and Ctrl-Y keys. It overwrites these new mappings in a
	small buffer area set aside in the .vimrc file. To change the comments
	mappings a small executable csh script called vip has been placed in
	your $HOME/bin directory. All you need to do is create an alias to this
	script which will allow you to load up the appropriate comments when
	you start a vim session.
	
	#!/bin/csh -f  
	# *** Path above is auto generated ***
	if(  ${#argv} != 0 ) then     # if we have a filename
			vpacm ${argv[1]}      # then run vpacm on it
		if( $? == 0) then         # if it's a valid file type 
			vim   ${argv[1]}      # then run vim on it
		else                      # otherwise
			echo "vim  ${argv[1]} not run!"
		endif
	else                          # vim not run so
			vpacm                 # display valid file extensions
	endif
																			
	So to create the alias edit the  $HOME/.bashrc file
	In my case I called the alias vm, so my .bashrc file contains the line:
				 
				 alias vm='vip $1'
				 
	Now when I need to change the comments style and load a file instead of
	"vi somefile.ext" I use "vm somefile.ext".  You only need to use vm if you
	are changing the comments type. I originally used the Ctrl-A key to load
	the mappings, but it meant you had to exit vim and re-enter vim so that
	your program could read the new .vimrc settings. It is still left in the
	.vimrc file, but I seldom use it.
	Do not make any changes to the mappings in the vpacm source file. Each
	pair of mappings occupy exactly 83 bytes. So any editing there will
	possibly corrupt the .vimrc file. Likewise do not edit the two top lines
	of the .vimrc file. This area has been set aside for vpacm and again you
	will possibly corrupt your .vimrc if you do. If you really wish to change
	things then make backups of .vimrc and vpacm.cc before starting.
	The .vimrc file contains a warning message regarding the X and Y mappings.

[CTRL-X] key: Comment Line[s]		
	CTRL-X  Will place comments on the line on which the cursor is positioned.
			Whitespace is not a problem. You can comment across whitespace
			between blocks of text(functions ect). Will not alter the layout
			(format) of your program.

[CTRL-Y] key: Uncomment Line[s]
	CTRL-Y  Will remove comments on the line on which the cursor is positioned.				Whitespace is not a problem. You can remove the previously set
			comments across blocks of text(functions ect). Will not alter
			the layout(format) of your program.

[CTRL-A] key: Set New Comment Type
	CTRL-A 	Will will change the comment type to the type of file loaded. To
			carry this out it first saves your work then examines the file
			type loaded and writes the comment type in the .vimrc file. For
			the new type to take effect it finally exits you from Vim. So that
			when you restart Vim the changes take effect. I tend to use the
			vm alias rather than this key. But I have left it in as an option.

EXAMPLE COMPILE:
^^^^^^^^^^^^^^^^
	In any sub directory in your home account imagine you have the
	following files. [ secure.c ezshell.c view.asm runp.c crypt.o]  You wish to
	compile and debug them. Normally you would either create a makefile
	which included the various build options,librarys ect. Or compile
	them on the command line along with the include options ect.
	Vpac makes this easier by examining each file in turn then calling
	the appropriate compiler-assembler to build the object files. Like
	a Make file they will only be built if they are not upto date. Finally
	they are linked with the main file to create the executable. All of
	the options for the compilers-assembler are stored in small scripts
	in the $HOME/etc directory. You don't normally need to touch these 
	files unless you are adding or removing options. 
	More on these script files under the /SUB-DIRECTORY/NOTES.
	Back to the Example Compile: In a terminal window run. 
	vi(Vim) secure.c [or vm secure.c if you also wish to set commenting to
	c style at the same time]
	With this file loaded in the window press the [F3] key. Each time you
	press the key it will display ON or OFF. In the OFF position if you pressed
	the [F10] key it would compile your program and not ask you for the other
	files to build. So the [F3] OFF mode is only used to build a single
	standalone file. 
	Ensure that the [F3] is ON. Now press the [F8] key also make sure
	this key is ON. (we are just checking the build options first)
	NOTE: When the [F8] Key is in the ON mode then only files that
	require updating will be displayed. Like "make -n" it only displays the
	options and does not run them. To use press [F8] to the ON position then
	press the [F10] key. For normal file building the [F8] key should be in
	the OFF position.
	A prompt will appear [Enter build files:] At this prompt, enter the
	other three file names, each filename seperated by a space.
	Example:
	Enter build files: ezshell.c view.asm crypt.o runp.c ... then press [enter].
	The build options will be displayed.
	
	:!vpac secure.c  2>&1|tee  mikes_2065
	Enter build files: ezshell.c  view.asm  runp.c
	gcc -c  -Wall -Werror -O2 -c -g ezshell.c 2>&1|mlfilter|tee
	nasm -g -i/usr/include/ASM/ -f elf view.asm 2>&1|mlfilter|tee
	gcc -c  -Wall -Werror -O2 -c -g runp.c    2>&1|mlfilter|tee
	gcc -c  -Wall -Werror -O2 -c -g secure.c  2>&1|mlfilter|tee
	gcc -o secure secure.o ezshell.o view.o crypt.o runp.o  -lstdc
	
	A quick note about locally written header or macro files.(.h,.inc or .mac)
	If for example your program secure.c had a locally written header
	file called rc4.h. You can optionally include this file at the build files
	prompt. Vpac will examine the file age of any include-macro or header
	files and will update the associated file[s]. In this case if rc4.h is more
	recent than secure.c or secure.o it will re-compile the secure.c file.
	All locally written header files must be in the current directory along
	with all source files. The Enter build files prompt is quite flexible in
	that it will accept .c .asm .cc .o .h .inc .mac in any order.
	
	Once you are satisfied with the build options
					[see subdir notes for changing them].
	Press the [F8]key OFF and then press [F10]. Re-enter the build filenames
	at the prompt and press the enter key. The files will be compiled and,
	linked to create the executable. But only if they require compiling. If 
	they are upto date then a message will inform you of this. To force a
	recompile touch any header files and include them on the build command
	line.
	[F11] key This key allows you to run the completed program. Any arguments
    to the program "secure" may be entered with the [F3] key ON. 
	In the [F3] OFF position, [F11] will not ask you for arguments and will
	just run the program.
	If the file secure.c failed its build with syntax errors press the [F6]
	to bring up the Vim(Quickfix) window which is set at 6 lines at the
	bottom of your source window. By pressing [F5] and [F4] keys you
	can scroll through the errors in your code. As you scroll the cursor
	will jump to the line where the compiler complained of a syntax error.
	Re-edit any errors and press the [F7] then [F10] key again and repeat the
	previous operations. [F7 closes Quickfix window] Continue to compile and
	check the Quickfix window until all syntax errors are fixed. Whilst in 
	the error mode the status line displays the ascii decimal and hex codes 
	of the character at the current cursor position.
	Having fixed the syntax errors and run the resulting executable. It  
	might still fail with an exception error. Time to step through your code
	and locate the bug.
	The [F12] is used to enter debug mode. All of the debugger commands can
	used in this mode.  like load - set args - step ect. The [F3]
	key has no effect in C C++ and Perl. It is only used when in assembly
	language mode to select either the ald or gdb debuggers. There is
	a file called gdbinit in the $HOME/etc directory which in [S]step mode in
	assembly displays the main processors registers and 6 lines of the
	program counter. You can edit this file to your own preferences.
	
	If you were  compiling a single file and by mistake the "Enter build
	files:" prompt appears ([F3] was on). Press the enter key and the
	compile will continue to build. Vpac will ignore empty parameters to
	the build files command. 
	So to recap. vm is used to set comment type. 
	[Ctrl-A] will also set comment type.
	[F3][F8][F10] used to check on the options. 
	[F3][F10] build commands. 
	[F4][F5][F6][F7] quickfix commands.
	[F11][F3] run commands. 
	[F12][F8] debug commands.
	Ctrl-X Ctrl-Y comment-uncomment commands.	
	[F2][F9] exit save commands.
	That concludes the build/compile/debug example.
	
SUB-DIRECTORY NOTES
^^^^^^^^^^^^^^^^^^^

	Ensure you have $HOME/bin in your environment Path otherwise the files
	in vpac will not run. See the README for instructions.
	The $HOME/etc directory contains all the configuration scripts for 
	[c, c++, gdb and nasm].  
	There are three files which control the link-library options and three
	files which control the compiler - assembler options. They are:

	c_options	 	(c compiler options) 
	cc_options  	(c++ compiler options)	
	asm_options  	(nasm assembler options)
	c_libraries  	(c link options)
	cc_libraries 	(c++ link options)    
	asm_libraries 	(ld link options)
	
	Each file consists of a one line options script. Only the first line
	is used. Any other lines are just options that can be used by swapping
	lines around.
	If you examine cc_options files in your $HOME/etc subdirectory it contains
	further notes on editing the options scripts.
	You will need to replace the options and libraries with your own
	compile and link option lines. The C/C++ scripts are suitable for general
	purpose builds. [edit them to your own preferences] But The asm scripts
	are sample lines only and unless you have the asmutils and libASM packages
	installed then they will fail. In the case of the asm options you could
	place in asm_options the following line which will work.
	-f elf 
	and leave the asm_libraries blank.  This will enable you to assemble
	sub routines to be used with C or C++ programs.
	The [F8] is used only to display these options prior to a build.
	There is one rule which applies to all of the option files. It is that
	vpac only reads the first line of the script and acts only on that line.
	You can store as many option lines as you like in the files then switch
	them around when you need to change options.
	The vpac program will read in the data from these files upto the first
	carriage return[0xa]. The options scripts must have a space at the end of
	the line of options. This reason for this is explained in the cc_options
	file. If you have so many options that they continue over the physical
	width of a window. Do not use the backslash \ symbol to continue the line
	as the 0xa char [cr] will still be at the end of the line. Use the Vim
	command "Shift j" to join the lines together instead.
	Lets examine examples from asm_options:
	
Line 1:
-w+orphan-labels -w+macro-params -i/usr/include/ASM/ -O1   -f elf -g -D__LINUX__ -D__KERNEL__=24 -D__SYSCALL__=__S_KERNEL__ -D__OPTIMIZE__=__O_SIZE__ -D__ELF__
-DDEBUG -DSTAMP_VERSION="'Vpac-0.0.1'" -DSTAMP_DATE="'29-Oct-2005 18:10'"

Line 2:
	 -i/home/mike/nasm/asmutils/inc/ -g -f elf -D__LINUX__ -D__ELF__
	
Line 3: -f elf -D ELF_TYPE	
	Line 1 comes from the asm_options file and is one continous line even
	though it might extend over several physical terminal window lines.
	This option would be included in the nasm assembly command. You can
	store more than one line of options in these files. But only the
	first line(1) of the file is read by vpac.
	Line 2: is a another asm option line. 
	Line 3: is yet another option line
	You can store as many option lines as you like.
	Using vim you can quickly swap these lines around in the script and change
	the build options. 
	ie: to include different libraries in the above case[ASM and asmutils]
	The same thing can also be done for the C/C++ scripts.
	
	The first time you press the [F3] or [F8] key in Vim, a small file
	called cmdline.arg is written and saved in your $HOME/etc directory. It 
	saves the status of the [F3] and [F8] keys for the [F10][F11][F12] keys.
	You do not need to touch this file, it is updated by vpac dependenent
	of which functions keys are being used.
	
	The gdbinit file is used to control the gdb debugger when debugging
	a Nasm file. It displays the 32bit register status, and the program
	counter. This is a kind of global .gdbinit file. Its currently set
	to display in intel mode just the same as you would write in Nasm. 
	It works with the [S]step key in gdb.
	Sample output from the gdb debugger: 
	
	  <bugs>s
	  _start () at showf.asm:15
	  15              mov     eax,5      ; the syscall number for open()
	  ______________________________________________________________
	  32mb Registers:
	  eax=0x00000000 ebx=0x0000003d ecx=0x0000003f    edx=0x0000003d
	  esp=0xbfffe058 ebp=0x00000000 esi=0x08048100    edi=0x08048100
	  ds=0x0000002b  es=0x0000002b  fs=0x00000000     gs=0x00000000
	  ss=0x0000002b  cs=0x00000023 eip=0x08048087 eflags=0x00000392
	  ______________________________________________________________
	  Program Counter:
	  0x8048087 <_start+7>:   mov    eax,0x5
	  0x804808c <_start+12>:  mov    ecx,0x0
	  0x8048091 <_start+17>:  int    0x80
	  0x8048093 <_start+19>:  test   eax,eax
	  0x8048095 <_start+21>:  jns    0x80480b2 <do_loop>
	  0x8048097 <_start+23>:  mov    edx,0x1a
	  --------------------------------------------------------------
	  <bugs>

	  You can change the configuration in the gdbinit file to suit your
	  own preferences.
	  
	In the bin directory there is a perl file called mlfilter. It
	is used as a pipe and filter between Vpac and the Vim(Quickfix)
	function. Its purpose is to make sure the error output fits in the
	Quickfix window. It works on  perl,assembly,gcc and g++ error output.
	You do not have to touch any of the files in your $HOME/bin/directory
	only the scripts in $HOME/etc/directory require adjusting to your own
	build preferences.
	The VIMRC in the /vpac-0.2/ directory contains the macros that runs 
	vpac. Make a backup of your existing .vimrc file. Then copy VIMRC to
	.vimrc in your $HOME directory. I have fully commented  the VIMRC so
	that the resulting .vimrc file will be easy to understand.
	But be  careful when changing options as you may prevent the error output
	to Quickfix from working correctly. So edit with care especially if you 
	are merging options from an existing .vimrc file with this one. Also in
	the .vimrc file the top two lines have been set aside for the comment
	options[Ctrl-X-Y]. So do not edit those lines.

VIMRC FILE:
^^^^^^^^^^^
	The VIMRC file must be copied to $HOME/.vimrc. I have commented every
	option in the file so it should be relatively easy to edit if you so
	wish. If you have an existing .vimrc file then make a backup of it before
	copying the vpac version into place. Use vimdiff to view differences and
	sdiff if you wish to do a merge, but make backups first.

ADDITIONAL NOTES:
^^^^^^^^^^^^^^^^^

	The vpac programs vpac,vpacr,vpacd must not be run under root.  Because
	these programs make use of shells. A possible root compromise might take
	place. To prevent this happening vpac will detect and reject any attempt
	to run under uid(0).
	This was the reason for building the vpac under a users ~/bin directory.
	You can run the vpac files from the command line. But they were really
	designed to work in a Vim session. This vpac will not work correctly from
	the gui version of Vim, as the gui version saves the object files created
	in the desktop folder and not in the current working directory where 
	vpac expects to find them.
	If you have the gui version simply open a terminal in Gnome or Kde and
	use [Vim - vpac] from there.
	The Gnome terminal uses the F10 key  by default. So you will need to
	go into the terminal properties box and click on disable properties
	[F10] This will allow the vpac [F10] key to work.
	This vpac was written and developed on a 586 laptop which has
	only 32mb of memory. Currently running CentOS-3 (2.4.21-27.0.1.EL).
	With no X11 or desktops. Just  a console.
	It has also been ported to and re-tested on a 686 running Redhat 9
	with both Gnome and Kde desktops.
															Mike Lear
