Repository files navigation

Welcome to PCjs, home ofPCx86, the original IBM PC simulation that runs in your web browser. It isone of several JavaScript Machines in thePCjs Project, an open-source project thatincludes:

• PCx86, an x86-based emulator of theIBM PC and PC-compatibles
• PC8080, an 8080 machine emulator (seeSpace Invaders and theVT100 Terminal)
• C1Pjs, an emulation of the 6502-basedOhio Scientific Challenger 1P
• PDPjs, a set of machine emulation modules supporting the DECPDP-10 andPDP-11
• PCjs Devices, for simple machines like theTI-57 Calculator, theGame of Life, andLite-Brite

All PCjs machine simulations are written entirely inJavaScript. No Flash, Java or other plugins arerequired. Supported browsers include modern versions of Chrome, Safari, Firefox, Internet Explorer (v9.0 and up), Edge,and assorted mobile browsers.

{% include machine.html %}

The PCjsmachine above usesPCx86 configured withan Intel 8088 running at 4.77Mhz, with 64Kb of RAM and an IBM Monochrome Display Adapter. The machine is also availablewith aControl Panel featuring the built-in PCx86 Debugger.For even greater control, build your own PC. ThePCx86 Documentation will help you get started.

PCx86 has steadily evolved to support more classic x86-based machines, including the IBM PC XT, the 80286-based IBM PC AT,and the 80386-based COMPAQ DeskPro 386. PCx86 fully supports the original machine ROMs, video cards, etc, and allmachines run at their original speeds.

The goals of thePCjs Project are to create fast, full-featured simulations of classiccomputer hardware, help people understand how these early machines worked, make it easy to experiment with differentmachine configurations, and provide a platform for running and analyzing old computer software.

Some pre-configured machines are shown below, ready to run BASIC, DOS, Windows, OS/2, and other assorted software.

There are many morePCx86 Demos, including anIBM PC with Dual Displays demonstrating early multi-monitor support,and multiple IBM PC XT machines running side-by-side withCGA DisplaysandEGA Displays.

Below is theOSI Challenger C1P, another simulation in the PCjs Project.It simulates Ohio Scientific's 6502-based microcomputer, released in 1978. More details about this simulationand the original machine are available in theC1Pjs Documentation.

{% include machine.html %}

ThePCjs Repository on GitHub contains everything needed to run PCjscomputer simulations. All the PCjs emulators run in any modern web browser, with or without a web server,and examples are provided for bothlocal andremote operation.

The project includes:

• A simple Node-based web server (server.js)
• Custom Node modules used by the web server (HTMLOut,MarkOut,DiskDump,FileDump)
• A variety of IBM PC and C1P configuration and resource files (see/apps,/devices and/disks)
• ThePCx86,PC8080, andC1Pjs client applications, along with "compiled"versions
• A smattering ofPCx86 andC1Pjs documentation, along withblog posts, relatedpublications and more

The bundled web server is not strictly required. Any web server (Node, Apache, Nginx, etc) that can serve the necessaryJavaScript files to your browser will work. However, instructions for doing that are beyond the scope of this introduction.

In fact, you can run PCjs simulations without a web server at all, using the "file:" protocol instead of "http:".However, most of the machine configurations require additional resource files (ROMs, disk images, etc), which areincluded in the project, but unless all the resource files are moved into a single directory (as they are in theseExamples), your browser will probably be unable to load all of them, due to security restrictions.Using the bundled web server is the preferred solution.

The project includes a large selection of disk images, and a powerfulDiskDump utility thatruns on both the client and server, featuring a command-line interface (CLI) and web server API. Originally created to dumpexisting disk images as JSON,DiskDump has evolved into a full-featured disk image generator, capable of creating PC-compatibledisketteand hard disk images from either listsor directories of files (including all subdirectories).

The following instructions were originally written for OS X. However, users of other operating systems should haveno problem following along. There are some prerequisites:

• Node with NPM (download an installation package for your OS fromnodejs.org)
• Git (included with OS X Developer Tools; separate download required forWindows)

Some additional (optional) tools are also recommended:

• Python (included with OS X; separate download required forWindows)
• GitHub (useful for getting Git set up onWindows; also available forOS X)

Once you have the prerequisites, open a command-line window,cd to the directory where you'd like to install PCjs,and type the following commands:

git clone --recurse-submodules https://github.com/jeffpar/pcjs.gitcd pcjsnpm install --productionnode server.js

Now open a web browser and go tohttp://localhost:8088/. You're done!

At the time of this writing, the recommended version ofNode was10.14.2.

Also,server.js was originally written usingExpress 3.x. Since then,Express 4.x has been released, butserver.js has not been updated; thenpm install command aboveshould ensure that Express 3.x is installed locally.

PCjs can also be used withJekyll and the Ruby WEBrick web server, now that ajekyll branch has been created to work withGitHub Pages. This is how the project is currently set up atpcjs.org.

This isn't going to be a Jekyll "How To" guide, because that would unnecessarily repeat all the information availableatGitHub Pages. But we'll summarize the basic steps, which replace thenpm andnodesteps above.

To install Jekyll for use with PCjs:

1. Install Ruby (on OS X, it should already be installed)
2. Install Bundler (on OS X, runsudo gem install bundler)
3. Checkout thejekyll branch, since only that branch contains all the Jekyll-related files
4. Create aGemfile containinggem 'github-pages' (this is already checked in)
5. Runbundle install (GitHub Pages alternatively suggests:bundle exec jekyll build --safe)
6. Runbundle exec jekyll serve to start the web server

Now open a web browser and go tohttp://localhost:4000/. You're done!

Some useful Jekyll server options include:

bundle exec jekyll serve --host=0.0.0.0 --config _config.yml,_developer.yml

The--host option makes it possible to access the web server from other devices on your local network;for example, you may want to run PCjs on your iPhone, iPad, or other wireless device. And by adding_developer.yml,you can override the Jekyll configuration defaults in_config.yml. Using development (non-production) settings in_developer.yml is analogous to running the Node web server with certain development options; seeDebugging PCjs.

GitHub Pages says you can runjekyll serve instead ofbundle exec jekyll serve, but with the addition ofmore gems toGemfile (eg, "jekyll-sitemap"), runningjekyll serve may trigger dependency errors on some systems.bundle exec jekyll serve should always work.

Don't see any YML files in the root of your project? You probably forgot to switch to thejekyll branch:

git checkout jekyll

Last but not least, runbundle update periodically to keep Jekyll up-to-date.

Unlike a typical project, where you have tobuild orconfigure ormake something, PCjs is "ready to run".That's because both the compiled and uncompiled versions of the PCjs emulation modules are checked into the project,making deployment to a web server easier.

However, in order to build and test PCjs modifications, you'll want to useGulp and theGulp tasks defined bygulpfile.js. If you already rannpm install --production as described above,then you should re-run itwithout the--production option:

npm install

to get all the development dependencies, including Gulp 4.x.

You'll probably also want to install the command-line interface to Gulp. You can install that locally as well, butit's recommended you install it globally with-g; OS X users may also need to preface this command withsudo:

npm install gulp-cli -g

Now you can rungulp anywhere within the PCjs project to build an updated version. If no command-line argumentsare specified,gulp runs the "default" task defined by the project'sgulpfile.js; that task runsGoogle'sClosure Compiler if any of the target files (eg, pcx86.jsin theversions directory) are out-of date.

The latestgulpfile.js now compiles all PCjs machine modules usingGoogle'sJavaScript-based Closure Compiler.

Runninggulp should build a complete set of "compiled" machine scripts in theversions directory.Individual machines can be compiled as well (eg,gulp compile/pcx86).

The PCjs Node web server is little more than a file/directory browser for the PCjs project, plus a collection of APIs.

If a URL corresponds to a PCjs project folder and no "index.html" exists in that folder, the Node web server loadsan HTML template (common.html) and generates an "index.html" for that folder.

The contents of the "index.html" will vary depending on the contents of the folder; for example, if the foldercontains a README.md, then that Markdown file is converted to HTML and embedded in the "index.html". Similarly,if the folder contains a machine XML file, that is embedded as well.

To work well with both the Node and Jekyll web servers, all Markdown files containing one or more embedded machinesshould contain a Jekyll "Front Matter" header that describes the machines. For example, here's the header from thepcjs.org home page (index.md):

---layout: pagepermalink: /machines:  - id: ibm5150    type: pcx86    resume: 1    name: "IBM PC (Model 5150) with Monochrome Display"    config: /devices/pcx86/machine/5150/mda/64kb/machine.xml  - id: demoC1P    type: c1p    config: /devices/c1p/machine/8kb/large/machine.xml---

Then the following lines are inserted at the points where the machines should appear:

{% include machine.html %}...{% include machine.html %}

For more information on all the machine options supported in a Markdown file, see the project's Jekyll include filemachine-engines.html.

The PCx86 client app can also be run from the command-line mode using Node, making it possible to script the application,run a series of automated tests, etc:

cd modules/pcx86/binnode pcx86

Thepcx86 script inmodules/pcx86/bin loadsall the PCx86 browser scripts listed inmachines.json and then starts a Node REPL("read-eval-print loop"). The REPL handles a few special commands (eg, "load", "quit") and passes anything elseto the PCx86 Debugger component. If no Debugger component has been created yet, or if the Debugger didn't recognizethe command, then it's passed on toeval(), like a good little REPL.

Use the "load" command to load a JSON machine configuration file. A sampleibm5150.json is provided in thebin directory, which is a "JSON-ified" versionof themachine.xml displayed on thepcjs.orghome page.

The command-line loader creates all the JSON-defined machine components in the same order that the browser createsXML-defined components. You can also issue the "load" command directly from the command-line:

node pcx86 --cmd="load ibm5150.json"

In fact, any number of "--cmd" arguments can be included on the command-line. A batch file syntax will eventually beadded, too.

When a PCjs machine runs in a browser, an XML machine configuration file is transformed into HTML with a set of DIVsfor each component: an "object" DIV whosedata-value attribute provides the initialization parameters for thecorresponding component, along with a set of optional "control" DIVs that the component can bind to (eg, aRun button,or a visual representation of DIP switches, or whatever).

When a PCjs machine is run from the command-line, there is no XML, HTML, or DIVs involved; this is basically a"headless" version of the machine, so there is no simple way to view its video display or interact with its keyboard,mouse, etc. You have to use Debugger commands to dump the machine's video buffer.

Since I was not inclined to add XML support to my Node environment, this has created some divergence between clientand server operation: PCjs machines on the client supportsonly XML machine configuration files, whereas PCjs machineson the server supportsonly JSON machine configuration files.

I haven't decided whether I'll add support for JSON configuration files to the client, or add some XML-to-JSON conversionto the server, or both.

NOTE: The following information assumes you're running Node as your local web server, not Jekyll. You can certainlydebug PCjs while running Jekyll (ideally with--config _config.yml,_developer.yml), usinghttp://localhost:4000/and your favorite web browser's Developer Tools, but none of the special server or client features discussed belowwill be available.

To help test/debug changes to PCjs server components (eg,DiskDump,HTMLOut),you can start the server with some additional options; eg:

node server.js --logging --console --debug

The--logging option will create anode.log that records all the HTTP requests,--debugwill generate additional debug-only messages (which will also be logged if--logging is enabled), and--consolewill replicate any messages to your console as well.

If you want server.js to use a different port (the default is 8088), set PORT in your environment before startingthe server:

export PORT=80

or add--port to your command-line:

node server.js --logging --console --debug --port=80

A complete list of command-line options can be found inserver.js.

A special command parameter ("gort") can be appended to the URL to request uncompiled client source files, making thePCjs emulators much easier to debug, albeit much slower:

http://localhost:8088/?gort=debug

The "gort=debug" command is unnecessary if the server is started with--debug; the server always serves uncompiledfiles when running in debug mode.

Conversely, if the server is in debug mode but you want to test a compiled version of PCx86, use:

http://localhost:8088/?gort=release

and the server will serve compiled JavaScript files, regardless whether the server is running in debug mode orrelease mode.

Another useful gort command is "gort=nodebug", which is like "gort=debug" in that it serves uncompiled files, butitalso sets the client-sideDEBUG variable tofalse, disabling all debug-only runtime checks in the clientand allowing the simulation to run much faster (although not as fast as compiled code):

http://localhost:8088/?gort=nodebug

Regrettably, the gort command "Klaatu barada nikto" is not yet recognized. Fortunately, there are no (known) situationswhere PCjs could run amok and destroy the planet.

Other parameters that can be passed via the URL:

• aspect: a numeric value >= 0.3 and <= 3.33 modifies the default aspect ratio of a machine's screen on the specified page; e.g.:

    http://localhost:8088/?aspect=2.0

• autoMount: overrides the machine's diskette autoMount settings; eg:

    http://localhost:8088/?autoMount={A:{name:"PC DOS 1.10"}}

• autoStart: "true" allows all machines to start normally, "false" prevents all machines from starting, and "no" prevents all machines from startingunless they have noRun button; e.g.:

    http://localhost:8088/?autoStart=false

• drives: overrides the machine's hard drive settings; e.g.:

    http://localhost:8088/?drives=[{name:"10Mb Hard Disk",type:3,path:"/disks-demo/pcx86/drives/10mb/PCDOS200-WIN101-EGA.json"}]

• autoType: a string of keys to inject into the machine after booting; e.g.:

    http://localhost:8088/?autoType=02-28-2018\r12:00\r

• mobile: "true" or "false" to override PCjs' mobile browser detection, which affects things like soft keyboard layout; e.g.:

    http://localhost:8088/?mobile=true&softKeys=true

• resume: a numeric value (0-3) overrides a machine'sresume setting; e.g.:

    http://localhost:8088/?resume=0

• softKeys: "true" to enable the machine's "soft keyboard" (if included); e.g.:

    http://localhost:8088/?softKeys=true

More information about theresume attribute is available in thedocumentation.

To start developing features for a new version of PCjs, here are the recommended steps:

1. Update the version numbers inpackage.json andmachines.json
2. Run the "gulp version" task to bump the version in all the machine XML files
3. Make changes
4. Run "gulp" to build new versions of the apps (eg, "/versions/pcx86/1.x.x/pcx86.js")

You might also want to check out the blog post onPCjs Coding Conventions.

You may also want to skip step #2 until you're ready to start testing the new version. Depending on the natureof your changes, it may be better to manually edit the version number in only a few machine XML files for testing,leaving the rest of the XML files pointing to the previous version. Run "gulp version" when the new version is muchcloser to being released.

In the course of testing PCjs, there may be stale "index.html" files that prevent you from seeing applicationupdates, changes to README.md files, etc. So before running Node, you may want to "touch" the default HTML template:

touch modules/shared/templates/common.html

TheHTMLOut module compares the timestamp of that template file to the timestamp of any"index.html" and will regenerate the latter if it's out-of-date.

There's a TODO to expand that check to include the timestamp of any local README.md file, but there are many otherfactors that can contribute to stale "index.html" files, so usually the safest thing to do is "touch" thecommon.html template, or delete all existing "index.html" files, eithermanually or with themodules/htmlout/bin/delete_indexes.sh script.

ThePCjs Project is now an open-source project onGitHub.All published portions are free for redistribution and/or modification under the terms of theGNU General Public License as published by the Free Software Foundation, either version 3 of the License,or (at your option) any later version.

You are required to include the following links and copyright notice:

PCjs © 2012-2020 byJeff Parsons

in every copy or modified version of this work, and to display that notice on every web page or computer that it runs on.

SeeLICENSE for details.

Learn more about thePCjs Project andPCx86. Tocreate your own PCx86 machines, see thePCx86 Documentation for details.If you have questions or run into any problems, feel free totweet oremail.