===== Installation =====
//Under Construction//
==== Download ====
[[download|Downloads]]
==== Environment Variables ====
Running W requires two mandatory and one optional environment variable :
  * WBIN => specifies the directory of all binaries that complement the language binaries: shared libraries (''*.so'' and ''*.dll''), external modules ''*.o''. Any subdirectories will not be considered.
  * WLIB => specifies the location of compiled W programs, standalone programs, and //library//. No subdirectories.
  * WSRC => required for compilation, optional for runtime. Specifies the base directory for program source code, files named ''*.w'': used by the interpreter and during compilation (for the [[reference#include|include]] instructions). This directory is also used by the debugger. If this variable is not set, it will not be possible to interpret the source code, and in //debug// mode, navigation within the original source code will not be available. Note that the source code will be searched for in the directory tree within WSRC.

==== Usage ====
To run a W program, both the main program and the //library//, three commands must be executed:
  - Compilation: The W source code is compiled into W //assembler//, in text format.
  - Assembly: The W assembler in text format is compiled into binary: this is the format recognized by the W runtime.
  - Execution: The W binary is interpreted by the W runtime. A //library// can only be called with the W binary version of the library being called.
Note: Modules called by //invoke// are shared libraries at the OS level (DLLs on Windows, so on Unix).\\

Additional executables:
  * W source formatter: This program allows you to (re)format an entire W source code in a uniform manner.
  * Lex rule compiler: This program compiles the lex rules (the format of W's internal engine) so they can be used in W programs as well as in the W runtime.

=== Compilation ===
<code>
>
> Usage: lwc [-WSRC:<path>] [-WLIB:<path>] <file>.w
>
</code>
The ''lwc'' compiler needs to know:
  * the directory containing the source code, to find the file to compile ''<file>.w'': environment variable WSRC, or failing that, the value of the -WSRC parameter on the command line
  * the directory where to put the resulting file, W assembler in text format, environment variable WLIB, or failing that, the value of the -WLIB parameter on the command line
The compiler stops at the first error encountered, displaying the error label, the line of source code concerned, and the error location.\\
Once the W program is compiled without errors, a file named ''<file>.wa'' will be created in the //WLIB// directory.

=== Assembly ===
<code>
>
> Usage: lwa [-c|u] [-WLIB:<path>] <file.wa|file.wp>
>
</code> 
The assembler "lwa" needs to know the directory where to read the source assembler file and where to write the generated w binary : the contents of the WLIB environment variable, or failing that, the value of the -WLIB command-line parameter. The assembler converts a ''*.wa'' file to a ''*.wp'' file.\\
The ''-c'' option in the assembly allows you to compress the generated //wp// binary. Compressed binaries are automatically handled by the disassembler (option ''-u'') and by the w runtime (program ''lw'' below).\\\
The assembler also allows disassembling a W binary by producing the assembler source code in text format : add the option ''-u'' to the command. The disassembler converts a ''*.wp'' file to ''*.wa''. The rule regarding the WLIB directory applies to both disassembly and assembly.

=== Execution ===
<code>
>
> Usage: lw [-d] [-t] [-WBIN:<path>] [-WLIB:<path>] [-WSRC:<path>] <prog> [parms...]
>

</code> 
The W runtime is launched with the executable ''lw''. The W runtime needs to know :
  * the directory containing the OS binaries (libraries used by the runtime), as well as the OS modules in binary form (called by //invoke//): environment variable WBIN, or failing that, the value of the -WBIN command-line parameter
  * the directory where to read the W binaries (main program, but also any //library//W), environment variable WLIB, or failing that, the value of the -WLIB command-line parameter
The W runtime is located in a directory present in the OS's //PATH//, and should therefore be found automatically by the shell.\\

The directory containing the base path to the sources (//WSRC//) is optional. It is useful if the debugger needs to be used. The ''-d'' option starts the runtime in debug mode on the program. The ''-t'' option displays the assembler instructions executed by the runtime for the requested program in the console. The runtime executes the binary program W <prog> (the ''.wp'' extension is not required).\\
The following are potential parameters that will be used by the W program (not by the runtime).

=== Formatting ===
<code>
>
> Usage: lwf <file.w>
>
</code> 
The formatter reads the input file, <file.w>, reformats it, and then overwrites the original file with the formatted version. The formatted version is also sent to standard output.\\
Formatting is done according to the //W// standard :
  * Indentation in increments of 3 spaces
  * End-of-line comments, starting with '';'', are separated from the code by spaces to align to a column width that is a multiple of 8
  * The following instructions raise the level: ''begin library background sub if loop foreach''
=== Lex Compilation ===
//Under Construction//