Document system requirements for building locally

[carolinan]

I cannot find documentation for the requirements for building the project locally.

Is Windows supported at all? After running npm install and trying to use
npm run dev or npm run build:website I am getting a lot of warnings.

The documentation in the readme.md file and on https://wordpress.github.io/wordpress-playground/architecture/host-your-own-playground#build-locally also lists different commands.

Examples:

'sleep' is not recognized as an internal or external command, operable program or batch file.

npm WARN config tmp This setting is no longer used.  npm stores temporary files in a special
npm WARN config location in the cache, and they are managed by
npm WARN config     [`cacache`](http://npm.im/cacache).

Warning: run-commands command "cp packages/playground/client/README.md dist/packages/playground/client" exited with non-zero status code

Warning: run-commands command "cp packages/php-wasm/web/README.md dist/packages/php-wasm/web" exited with non-zero status code

Error: Illegal characters in path.
    at pathArg (D:\wordpress-playground\node_modules\rimraf\dist\cjs\src\path-arg.js:45:33)
    at D:\wordpress-playground\node_modules\rimraf\dist\cjs\src\index.js:40:80
    at Array.map (<anonymous>)
    at D:\wordpress-playground\node_modules\rimraf\dist\cjs\src\index.js:40:42
    at main (D:\wordpress-playground\node_modules\rimraf\dist\cjs\src\bin.js:245:15)
    at Object.<anonymous> (D:\wordpress-playground\node_modules\rimraf\dist\cjs\src\bin.js:255:5)
    at Module._compile (node:internal/modules/cjs/loader:1256:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1310:10)
    at Module.load (node:internal/modules/cjs/loader:1119:32)
    at Module._load (node:internal/modules/cjs/loader:960:12) {

>  NX   Ran target build for project playground-website and 21 task(s) they depend on (35s)

    ×    5/14 failed
    √    9/14 succeeded [0 read from cache]

[eliot-akira]

requirements for building the project locally

The build scripts require Linux, macOS, or Windows Subsystem for Linux (WSL2), due to the use of UNIX commands like cp and sleep.

It's true, this would be helpful to note in the documentation.

also lists different commands

The documentation section, Architecture -> Host Your Own Playground -> Build Locally, shows the minimum commands to build the website for deployment to your own server.

In comparison, the section in readme.md called Running WordPress Playground locally lists various commands for local development purpose.

The main one is npm run dev which builds the website, then waits for any file changes and refreshes the website (using "hot reload" which updates the site without having to reload the browser tab completely).

In addition, there's a whole list of other commands using nx, which it says has to be installed globally - but doesn't show how: it's npm install -g nx. (Or, if you prefer not to install it globally, you can use npx nx instead of nx. For example, npx nx build docs-site instead of nx build docs-site.) These commands are for building packages that compose the Playground project, such as the documentation site, and compiled files for each supported version of WordPress and PHP. For these latter, Docker must be installed.

[adamziel]

@carolinan were you able to make it work with WSL2? As @eliot-akira noted, it would be great to note the system requirements in the documentation.

Aside, I'm super interested in your use-case for generating a custom build.

[carolinan]

The end goal was to have a demo of the Site Editor only. But a big part is also just learning how it works by hacking it.
I have not had a time to try again since I last wrote here :)

I do not have an environment set up on Windows right now so I can't test.

[adamziel]

@carolinan you could restrict Playground to just the site editor with an mu-plugin that would redirect from all other URLs back to the site editor. Would that do the trick? If so, you could set it up with a Blueprint like this one:

{
    "steps": [
        {
            "step": "writeFile",
            "path": "/wordpress/wp-content/mu-plugins/editor-only.php",
            "data": "<?php // your code "
        }
    ]
}

If you need a custom Gutenberg build for that, you could prepare just that and then install it using the installPlugin step.

Also see how @akirk built the GlotPress Playground (view the source of that page).

[juanmaguitar]

In addition, there's a whole list of other commands using nx, which it says has to be installed globally - but doesn't show how

I opened the PR #1325 to provide from the README the resource to install nx globally