Building An Executable

Thursday 21 November 2024 19:13 UTC NARS2000 Building The Executable

Why Build Your Own

Why not? Many people think and believe Kenneth Iverson's work remains that of a true genius, a bright light among some very bright intellectual lights, both from a theoretical as well as a software implementation perspective. Here's your opportunity to attempt to improve upon some very substantive, preexisting software development work - to further it, to make it even better, and perhaps best of all - it's free.

Personalize some already pretty amazing software for yourself, or share it with others and get their feedback for even greater insight and subsequent improvement. NARS version of APL already has over a quarter million lines of source code, subroutines, macros, functions, etc. - 50 years of sometimes intense and continuing evolution, so you are not creating something from undeveloped scratch, but inheriting and working from already highly evolved, rigidly disciplined concepts and rigorously debugged software over time.

APL has been used in physics, science, robotics, engineering, artificial intelligence, VLSI, financial, statistical and social science applications. NASA and Astronomy have used it.

Now APL is 100% customizable. Perhaps you will be the first to customize APL to safely drive a vehicle, help save a life, make new discoveries or make some process(es) more efficient.

It's free. It's evolved. And it is a great opportunity to learn more about the human-machine interface; how machine hardware operates and better understand how software and hardware interact together. One of the magnificent aspects of APL is how fully it spans the breadth of hardware functionality including - instructions running core processor chip(s) and peripheral devices. This is not your grandparents' punch card software program run on a room-sized computer that may have taken him/her several days to get results back for in an introductory chemistry or math lab course. On the other hand, data structures influence speed of quantum search in unexpected ways.

Platforms

The current version of NARS2000 may be built on Windows platforms only, however a goal is to enable it to built on Linux, Mac OS, etc. as per user requests and developer interests. As such, for the moment, the following description for building an executable is necessarily biased towards Windows.

Downloads

To build the executable in summary you'll need the following:

1. C Compiler and Linker
   1. Make program
   2. Resource Compiler
   3. Windows SDK
2. Parser Generator
3. Zip Utility
4. PHP (Hypertext Preprocessor)
5. NARS2000 Source Code
6. NARS2000 External Libraries
7. Optionally, Multi-precision Library Source
8. STDINT.H header file
9. Version Control program
10. Doctor Dump SDK
11. Optionally, a File Differencing/Merge program

All of the tools you'll need are freely available. Some of them happen to be Microsoft-specific. Bill Gates while at Harvard actually worked a bit on/with APL, obviously he discovered the importance of working with arrays and symbolic notation. At the same time there is no reason more generic tools (such as DJGPP, Cygwin or MinGW) can't be used, a task NARS is hoping someone will volunteer to investigate. In particular, the tools currently used to create the APL Executable, in detail, are as follows:

1. C (needed for this NARS2000 project is Visual C++ 2008 = C++ GUI development environment and compiler for the C language, which much of APL is written in). Compiler and Linker: Microsoft Visual Studio 2008 Express (requires Windows XP or later) — includes Link, Make, a Resource Compiler, and an SDK (among others). Download/Installation Notes: The downloaded .iso file may be double-clicked in Windows Explorer, then double-click on Setup.hta, then from the menu choose Visual C++ 2008 to setup/install on your machine. C++ does NOT Install to a mapped or network drive(but to something like C:\Program Files\...). It must be Installed on a local PC drive (e.g. C:\...) and unmapped directory (but you can map to it later) - Microsoft apparently requires installation to a local machine drive letter such as "C:\..." It is free and it includes a GUI or graphical user interface(icon-based), which is geometrically easier to use than a command-line interface.
2. Parser Generator: Bison, a Cygwin package, (Save and run either setup-x86.exe (32-bit systems) or setup-x86_64.exe (64-bit systems) as appropriate to your system, Choose A Download Source: Install from Internet, Select Root Install Directory, Select Local Package Directory, Select Your Internet Connection, Choose A Download Site, Select Packages: Leave alone All (Default) - first time through, just click [Next], Devel, and bison, other dependent packages will be installed along with bison)
3. Zip Utility: 7-Zip (Latest version, 32- or 64-bit, as appropriate to your system; needed to Extract/Unzip the files and folders you are downloading for this project.) If you already have a Zip utility program on your PC, Tablet or Server such as WinZip, you can normally skip the 7-Zip download/install.
4. PHP (Hypertext Preprocessor): Downloads (Windows downloads for Windows systems.) (Windows binaries/VC9 x86 Thread Safe/Latest version/Zip or Installer, your choice) (Items to Install: Entire Script Executable, and entire Extras). Place the unzipped file's contents into something like "C:\PHP". The executable file "php.exe" needs to be "on your directory or environmental path" when later compiling or building the APL executable.
5. NARS2000 Source Code: Click on Browse Code button at NARS SourceForge.net code repository. You may also use a Version Control program, e.g. see Tortoise SVN below and here, see their download page.
   Prior non-current NARS Source Code versions available at Code Google.
6. NARS2000 External Libraries: Miscellaneous Library (misc.zip, which contains 4 .php files and 1 .ttf file - all directly unzipped into C:\NARS2000) and the following NARS libraries:
   1. MPIR/MPFR/ECM Libraries - These libraries(mplibs.zip) should be directly extracted or unzipped into the C:\NARS2000 folder such that three(3) distinct sub-directories are directly created: \ecm, \mpfr and \mpir, e.g. C:\NARS2000\ecm.
   2. gsl Library - This library(gsldir.zip) should be directly un-zipped into the C:\NARS2000 folder such that it becomes C:\NARS2000\gsl. Folder structure "C:\NARS2000\gsldir\gsl" would be invalid.
   3. qdebug Library - This library(qdebug.zip) should also be directly un-zipped into the C:\NARS2000 folder such that it becomes C:\NARS2000\qdebug. Make sure it is NOT double-enclosed when unzipped, for example the following would be an invalid folder setup structure: C:\NARS2000\qdebug\qdebug.
7. Multi-precision Library Source Code: MPIR/MPFR/ECM Source. This zipped download is large (roughly 0.5GB) and is needed primarily to reproduce files in the MPIR/MPFR/ECM Library download so as to satisfy requirements of the GNU General Public License (GPL) v3. For more details on using the files in the download, look in the zipped file for readme.txt. If you are content to use the already-compiled existing binary libraries in MPIR/MPFR/ECM Libraries, you may not immediately need the MPIR/MPFR/ECM Source Code; on the other hand - 128-bit CPU chips are in manufacturing production pipelines, quadruple-precision 128-bit floating-point format has been standardized by the IEEE and ultra-precise calculations are already needed in such fields as quantum physics, ref. Physicists take quantum leap toward ultra-precise measurement, 6/2/2014. One of APL's strengths is its handling of mathematically precise calculations and the large size of the multi-precision source code library reinforces that.
8. STDINT.H header file installed in the MS VS 2008 Express include directory (V:\VC\include -- see below)
9. SubVersion Control program: Tortoise SVN (Current version, 32- or 64-bit depending upon your OS)
10. Doctor Dump SDK: Doctor Dump SDK - e.g. DoctorDumpSDK.zip.
11. File Differencing/Merge program: WinMerge (Latest stable version, usually downloads to something like WinMerge-k.m.n-Setup.exe where k, m and n are version/sub-version numbers.)

Install Tools

Preface, Convention: x86 generally refers to 32-bit software installations while 64 (or blank) represents 64-bit software installations on a Windows OS machine. NARS works on both 32-bit and 64-bit systems, but you should decide in advance which type of install you want 64 vs. 32-bit - ditto for all tool installs. Installation examples:

1. C:\Program Files (x86)\        Represents 32-bit software program installation, normal folder location.
2. C:\Program Files\                 Represents 64-bit software program installation, normal folder location.

Also, both folder locations just above frequently and even always exist on most machines, but for consistency and integration purposes the software should be 32 or 64-bit. Most people choose 64-bit installs if their Windows OS supports the 64-bit architecture, with 32-bit available for backward software compatibility in conjunction with less current systems. If you don't know which architecture your system uses, go to the Control Panel, System Information. Downloads usually get placed into a Downloads folder. Several of the unzipped NARS tools get placed directly into the C:\NARS2000 folder, see individual tools for exact locations.

To install the Microsoft Visual Studio 2008 Express C compiler, see Downloads(detail, #1 above). Visual C++ 2008 usually installs into something like, "C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\VCExpress.exe" (64-bit loc) and you may want to place a Shortcut to VCExpress.exe on your Desktop by right-clicking on that VCExpress.exe file in Windows Explorer and Send To - Desktop (create shortcut). (Windows 8 Users: You can also Pin VCExpress.exe To your Taskbar for quick, easy access.) (Prior/obs. Microsoft setup routine name: run the vcsetup.exe program.) Afterwards including after drive plus folder remapping - the files msobj80.dll, mspdb80.dll, mspdbcore.dll, and mspdbsrv.exe all need to be copied from V:\Common7\IDE to V:\VC\bin, where the V drive is a substitute/mapping for C:\Program Files\Microsoft Visual Studio 9.0. See the discussion below on Set Up Makefile Environment Variables.

To install the Parser Generator (Bison), see the instructions above. When the Cygwin setup program asks you to choose a Default Text File Type, choose DOS/text so any committed files are the same as in the version control repository.

To install the Doctor Dump SDK, unzip it in any directory at or above %NARSROOT%. See the discussion below on Set Up Makefile Environment Variables.

Install the rest of the tools as per their instructions above, in the Downloads section.

Install The Source Code

1. First create a NARS2000 root folder somewhere on one of your hard drives, perhaps calling it NARS2000, as in C:\NARS2000 (most common) or perhaps at some lower level. The source code and external libraries are typically installed at or into this level, e.g. qdebug.zip into C:\NARS2000 as C:\NARS2000\qdebug.
2. Under the root folder make three folders: trunk, msieve, and branches. The first folder (trunk) will hold the main body of NARS/APL built exe interpreter source code. The second (msieve) will be utilized for code used to factor numbers, and the third (branches) will contain individual developer branches of the main code not as yet ready for release, but made public for other developers to see.
3. Using a Version Control program such as TortoiseSVN, download-checkout the source code (see Check Out The Source Code),
4. Download the misc.zip, qdebug.zip, gsldir.zip, and mplibs.zip files into the root folder and unzip them (directly into that root folder, e.g. C:\NARS2000) using e.g. 7z.exe (unzip/extract program used) as in 7z x misc.zip, 7z x qdebug.zip, 7z x gsldir.zip, and 7z x mplibs.zip - or double-click on those downloaded zip file names using Windows File Explorer and Extract All (again typically directly into NARS root folder previously set up).

Check Out The Source Code

An easy way to initialize your copy of the source code for the first time, although it may initially appear cumbersome to an SVN "newbie," is to use a version control program such as TortoiseSVN, mentioned above. One very helpful feature of TortoiseSVN is that it integrates well with Windows File Explorer. After downloading and installing TortoiseSVN and then rebooting your PC, there are two directories you'll need to Install/initialize-checkout/TortoiseSVN-on.

1. First, bring up Windows Explorer, right-click on the trunk folder you manually created, and choose SVN Checkout.... The online NARS URL of repository: is svn://svn.code.sf.net/p/nars2000/code/trunk and your local Checkout directory: is C:\NARS2000\trunk (or wherever your trunk folder is) — quite likely you will have to edit the repository or local folder field as the default text inserted by TortoiseSVN usually does not match location(s) identically.
2. Second, bring up Windows Explorer, right-click on the msieve folder you likewise manually created - and choose SVN Checkout.... This time online NARS URL of repository: is svn://svn.code.sf.net/p/nars2000/code/msieve and your local Checkout directory: is C:\NARS2000\msieve (or wherever your msieve folder is).

In both checkout cases - the Checkout Depth should be Fully recursive. Click on OK to initialize your copy of the source code, re trunk and msieve folders.

The above two steps/distinct-folders need be initialized this first checkout time through - in order to establish the special hidden SVN directories for subversion "synching" between your local source code and the online code repository.

You will still or now need to download and unzip qdebug.zip, misc.zip, gsldir.zip, and mplibs.zip as described above.

Subsequently, you may quickly and easily update your local copy of NARS source code by right-clicking on the trunk and/or msieve folders and choose SVN Update. One useful feature of sub-versioning programs such as TortoiseSVN is that only changed files from the online latest official version will need to be subsequently downloaded as changes are made in futuro, re subsequent NARS revisions.

Folders

After unzipping the above files, the structure under the NARS2000 root folder should look very much like the following(leftmost column), where lower level sub-directories and individual sub-folder file names have been omitted:

NARS2000 SubFolder:	Downloaded Zip Source File or Checkout Process:
branches\	Created manually(1)
ecm\	mplibs.zip
gsl\	gsldir.zip
mpfr\	mplibs.zip
mpir\	mplibs.zip
msieve\	TortoiseSVN Checkout msieve
qdebug\	qdebug.zip
trunk\	TortoiseSVN Checkout trunk
trunk\binaries\	TortoiseSVN Checkout trunk
trunk\Extensions\	TortoiseSVN Checkout trunk
trunk\htdocs\	TortoiseSVN Checkout trunk
trunk\images\	TortoiseSVN Checkout trunk
trunk\MediaWiki\	TortoiseSVN Checkout trunk
trunk\ReleaseNotes\	TortoiseSVN Checkout trunk
trunk\WineHQ\	TortoiseSVN Checkout trunk

(1) Subfolder \branches should be created manually (e.g. Windows Explorer, right-click, New, Folder). It is used to hold subprojects you may develop. For example if your name is Bill Gates, you might have the following subfolders, each representing a NARS subproject:
C:\NARS2000\branches\bgates\NARS_Spreadsheets
C:\NARS2000\branches\bgates\NARS_WordProcPlusAPLEdits
C:\NARS2000\branches\bgates\EZMenus
C:\NARS2000\branches\bgates\Graphics

Choose How To Build

The following sections describe two alternate ways to build the executable. One is the GUI interface of VC++ Express, the other is a command line interface using a makefile.

Set Up VC++ Express

If you are using VC++ Express, the project file is in the trunk folder and is called NARS2000.vcproj. You may load it manually every time you invoke VC++ Express, or you may load it automatically by placing the path to the project file on the command line in the VC++ Express shortcut as in "C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\VCExpress.exe" C:\NARS2000\trunk\NARS2000.vcproj or wherever you defined your NARS2000 root folder.

The vast majority of the project settings are found in the above file with some exceptions.

Set Up Makefile and Environment Variables

---

Windows 8: Setting up Environment and Path Variable(s): Under Settings, Control Panel, System and Security, System, Advanced System Settings, Advanced (Tab) or in Control Panel Search for Environment Variables,

• Click Environment Variables button - There is both a Temp Variable and Path Variable.

There are 2 sections, User Account Variables and System Variables. You normally want to add new System Variables.

Click [New] button for a New System Variable:

Variable name       PARGEN

Variable value       C:\cygwin64\bin\bison       << typical for a 64 bit install(for bison.exe in subfolder bin), for 32 bits installs see below for variable set values.

• Normally add a New variable (var Name plus Value) for each of the Set commands listed below, vars such as NARSROOT, CS_DIR, ZIPPRG, PARGEN, etc.
• If you need to add another Path to an existing variable, each new or added path is separated with a semi-colon.
• After updating any Environment/Path variable(s) you apparently need to reboot since the above variable changes only affect changes in the Registry until PC is rebooted.
• The instructions below should also or alternatively work.

---

If you are building from the makefile or working with the GUI C++ Compiler, you'll need to set eight environment variables in your autoexec.bat file (or see just above for setting Environment Variables via Windows Control Panel). Note that Environment variable #n's just below are shown only for helpful reference purposes.

REM Path of the root of the NARS2000 project *ending with a backslash*
Set NARSROOT=C:\NARS2000^\                         Environment variable #1

REM Path to Doctor Dump SDK root
Set CS_DIR=C:\DoctorDumpSDK^\                      Environment variable #2

REM Path and name of zip program (7-Zip)
Set ZIPPRG="C:\Program Files\7-Zip\7z"             Environment variable #3

REM Path and name of parser generator (bison)      Environment variable #4 (next line)
Set PARGEN=C:\Cygwin\bin\bison         OR for a 64-bit install >>   Set PARGEN=C:\cygwin64\bin\bison

REM Path and name of makedep program
Set MAKEDEP=%NARSROOT%makedep.php                  Environment variable #5

REM Path and name of the <makepro.php> program
Set MAKEPRO=%NARSROOT%makepro.php                  Environment variable #6

REM Folder of SDK ("C:\Program Files\Microsoft SDKs\Windows\v7.0A")
Set SDK=U:^\                                       Environment variable #7

REM MSVC compiler ("C:\Program Files\Microsoft Visual Studio 9.0")
Set MSVC=V:\VC^\                                   Environment variable #8

---

Mapping Virtual Drive Letters:

Method 1(sometimes preferred, although the interface is command-line based): Using Windows subst command to map drive letters as in the references to drives U: and V: above. Microsoft explanation of Subst here.

subst U: "C:\Program Files\Microsoft SDKs\Windows\v7.0A"      (or whatever the current version is)

subst V: "C:\Program Files\Microsoft Visual Studio 9.0"             (ditto re version 9.0=Visual Studio 2008)

---

Method 2(GUI based): Using freeware vSubst - Visual Subst v1.8.02 or higher freely available, download from Thomas Bigler vSubst, developer website at Thomas Bigler, vSubst program description toward bottom of webpage:

• First open Windows Explorer, perhaps navigating to the correct folder, e.g. C:\Program Files\Microsoft SDKs\Windows\v7.0A" (or whatever the current version is)
• Unzip vsubst.zip into folder in your Downloads folder, in that resultant unzipped folder, double-click on program vSubst.exe (no install needed) to start vSubst program. Choose/click an available drive letter, e.g. U. Then switch back <Alt-Tab> to Windows Explorer window, hit <Alt-D> (to choose and highlight folder's complete address) or manually go to navigated folder address text box, hit <Ctrl-C> to Copy (all SDKs/VS 9.0 address) linking folder name. Switch back <Alt-Tab> to vSubst, click [Add] button, hit <Ctrl-V> to Paste folder address into vSubst text box, click [OK] button to create virtual drive link, click [Persistent] button to allow auto-relinking at logon/reboot; repeat process for V.

U =     C:\Program Files\Microsoft SDKs\Windows\v7.0A     (or v6.0A or whatever your downloaded/current version is)

V =     C:\Program Files\Microsoft Visual Studio 9.0           (ditto re version 9.0=Visual Studio 2008)

Although not normally needed, unless you inadvertently mapped the wrong subfolder, unmapping a drive is just as easy: open vSubst.exe, choose substituted folder to remove, click [Remove] button. This unmapping works only for virtual drives you originally set up with vSubst.exe.

As a check to make sure the Subst commands worked, there should now be 2 new drive letters visible in Windows Explorer, in the leftmost window for virtual drives/mapped folders - U and V.

---

If you install NARS project tools in other folders, make appropriate changes to the above mappings.

You will also have to append folders C:\Cygwin\bin and V:\Common7\IDE to your Path variable (PATH=%PATH%;C:\Cygwin\bin;V:\Common7\IDE or see Control Panel search for Path, then Edit environment variables for your account, system variable named Path; append to that Path variable ;C:\Cygwin\bin;V:\Common7\IDE) so C's compiler can find DLLs and tools you have so diligently downloaded and installed.

Building The Executable

At this point you should be ready to build the executable. To do this from VC++ Express (having already opened the project file), click on the menu item Build | Build Solution or press F7. To do this from a makefile, type mkn.