Nexus-Mods / Vortex

Vortex Development
GNU General Public License v3.0
848 stars 127 forks source link

Vortex

Last Commit Build Release Pre-release Contributors Forks Stars Watchers License GPL-3.0

Nexus Mods Discord

Windows Electron.js NodeJS React Redux SASS Webpack Yarn JavaScript TypeScript

Building from source code

To build from source you have two choices.

1) Automatic (mostly):

2) Manual:

Node.js
Yarn
Git
Python 3.10
CMake
Visual c++ build tools 2022 or Visual Studio 2022 (Community Edition)
Set up yarn to use C++ build tools

Cloning and building the Vortex source code

If something goes wrong

There are two phases to the process, installing dependencies and building. However, dependent modules may also be compiled during the install phase, this is particularly true for native modules (modules written in C++ for example rather than javascript) if no pre-build binaries are available online. Thus you might get compilation errors during the "yarn install" step.

If the install step fails with an error mentioning c++ or node-gyp or cmake, this will usually mean that one of the tools (python, cmake, visual studio build tools) were not installed (correctly) or can't be found, please repeat the corresponding step above and double check you followed the instructions. Then repeat the "yarn install" step. Unfortunately, with these tools being installed system-wide, it's also possible that your existing installs of other versions of these tools (visual studio build tools in particular) may interfere. We can only really promise this build works on a clean windows.

There is one component, fomod-installer, written in c# and at the time of writing its build will randomly fail for no reason. In this case you don't have to do anything special, just repeat the install step.

If the error message shows an error from webpack or a javascript error, this may mean that some package was updated and broke compatibility. It may also mean typescript is outdated. Another possible error may be that your yarn cache is invalid such that even if you reinstall a package you still get a broken variant. The yarn cache is at %LOCALAPPDATA%\Yarn\Cache\v6 and it's safe to delete it, that will only cause some additional internet traffic.

The automatic variant will skip dependency download and install if the download was installed previously. If a dependency install failed for some reason or you cancelled it, you will have to manually install that package (see the downloads directory).

Running the dev build

After building a dev build you can run it using yarn start

You can repeat the steps to install dependencies (yarn install) and the full build (yarn build) as necessary.

To save yourself time, you can rebuild just the bundled extensions (yarn run subprojects). If you're making changes to the core application you can run build in watch mode (yarn run buildwatch) which will be the same as yarn build but then will continue to watch for changes (only on the core application, not extensions!) and rebuild on demand.

Development decisions

The following section aims to clarify and explain a few development decisions.

development vs release builds

The toolchain for development builds and release builds is quite different.

In dev builds the typescript compiler (tsc) is used directly to transliterate each ts file to js individually, electron runs those files directly, dependencies are loaded from node_modules.

In release builds we use webpack and ts-loader to bake all ts files and dependencies into two javascript files (one for the main/browser process, one for the renderer). electron-builder is used to bundle code&assets, generate an nsis installer, build it into (two variants) of exe installers and sign them (and all the executables and dlls we ship). There are mulitple electron-builder configuration files for multiple variants, only "oneclick" and "advanced" are used for release builds, the others may be in different states of disrepair (though ci should work as well)

As a result, dev builds are easier to work with and building is much quicker but runtime is substantially.

Further, we use a two-package structure, meaning the /package.json file is used for all development and the build environment for releases (e.g. this file always controls the electron version being used/bundled) whereas /app/package.json decides settings (name, version, dependencies) for the release builds only. We use a custom script (checkPackages.js) to ensure that the dependencies for release are a subset of the build env dependencies and that they use the same version to avoid problems that didn't occur during testing because of differing dependencies.

Bundled extensions on the other hand are built the same between dev and release: they are always built with webpack and each have their own build setup - with the exception of simple game extensions which are already single js files, those simply get copied over.

yarn 1 vs yarn 3 vs npm vs pnpm

This codebase still use yarn 1 (classic). Any attempt to use yarn 2 or 3 ended up with nonsensical errors (missing dependencies that are clearly listed, successive installs leading to missing packages) with no reasonable way to investigate why. npm and pnpm are quite slow in comparison. We don't really use any yarn-specific features (workspaces?) so switching shouldn't be too difficult but for now yarn "classic" works.

esm vs commonjs

At the time of writing, electron doesn't support ES modules so everything is transpiled to commonjs. This has the consequence that some updated libraries supporting only esm can't be used (e.g. new versions of d3). It also means that asynchronous imports (const foo = await import('bar')) are actually synchronous at runtime. Doesn't really matter though since everything is baked into a single file on release builds anyway and code splitting isn't really needed.


Further Information

Reporting bugs

Please report issues to the issue tracker on github. Please always include at the very least the following information:

All data the client generates (including settings and logs) are stored at

C:\Users\<username>\AppData\Roaming\Vortex (releases)

or

C:\Users\<username>\AppData\Roaming\vortex_devel (development build)

If you need to report a bug, the following files inside that directory may be useful in addition to the error message displayed on screen: