plastichub/nodeguy
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

moved back docs to toplevel

Browse Source
This commit is contained in:
Atul R
2019-07-30 22:49:41 +02:00
parent e8bccc9eff
commit 1eb39cdb3c
9 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
extras/docs/.nojekyll
View File
extras/docs/README.md
-34
View File
@@ -1,34 +0,0 @@
# Guides and Tutorials
- [About NodeGui](tutorial/about.md)
- [Setting up the Development Environment](tutorial/development-environment.md)
- [Setting up macOS](tutorial/development-environment.md#setting-up-macos)
- [Setting up Windows](tutorial/development-environment.md#setting-up-windows)
- [Setting up Linux](tutorial/development-environment.md#setting-up-linux)
- [Choosing an Editor](tutorial/development-environment.md#a-good-editor)
- [Creating your First App](tutorial/first-app.md)
- [Hello World](tutorial/first-app.md#Hello-World)
- [NodeGui Development in a Nutshell](tutorial/first-app.md#NodeGui-development-in-a-nutshell)
- [Running Your App](tutorial/first-app.md#running-your-app)
- [Application Architecture](tutorial/application-architecture.md)
- [Qode](tutorial/application-architecture.md#qode)
- [Using NodeGui's APIs](tutorial/application-architecture.md#using-NodeGui-apis)
- [Using Node.js APIs](tutorial/application-architecture.md#using-nodejs-apis)
- [Using Native Node.js Modules](tutorial/using-native-node-modules.md)
// BOOK MARK - TODO AFTER THIS
- [Testing and Debugging](tutorial/application-debugging.md)
- [Debugging the Main Process](tutorial/debugging-main-process.md)
- [Debugging the Main Process with Visual Studio Code](tutorial/debugging-main-process-vscode.md)
- [DevTools Extension](tutorial/devtools-extension.md)
- [Distribution](tutorial/application-distribution.md)
- [Supported Platforms](tutorial/support.md#supported-platforms)
- [Code Signing](tutorial/code-signing.md)
- [Mac App Store](tutorial/mac-app-store-submission-guide.md)
- [Windows Store](tutorial/windows-store-guide.md)
- [Snapcraft](tutorial/snapcraft.md)
// Need to finish till here
- [Getting Support](tutorial/support.md)
## Development
See [development/README.md](development/README.md)
extras/docs/index.html
-42
View File
@@ -1,42 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>
@nodegui/nodegui - A cross platform library to build native desktop apps.
</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta
name="description"
content="A cross platform library to build native desktop apps."
/>
<meta
name="viewport"
content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"
/>
<!-- <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css" /> -->
<!-- <link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css"
/> -->
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css"
/>
</head>
<body>
<div id="app">Loading documentation...</div>
<script>
window.$docsify = {
name: "NodeGui",
repo: "https://github.com/nodegui/nodegui",
themeable: {
readyTransition: true, // default
responsiveTables: true // default
}
};
</script>
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/docsify-themeable@0"></script>
</body>
</html>
extras/docs/tutorial/about.md
-27
View File
@@ -1,27 +0,0 @@
# About NodeGui
[NodeGui](https://nodegui.github.io/nodegui) is an open source library for building cross-platform desktop applications with JavaScript and CSS like styling. NodeGui accomplishes this by combining the powers of [Node.js](https://nodejs.org) and [Qt](https://www.qt.io/). NodeGui apps can be packaged for Mac, Windows, and Linux.
NodeGui began in 2019 as part of frustrations related to Electron and other chromium based cross platform Gui solutions. Electron is a great framework for building cross platform apps but suffers from performance and energy related issues due to heavy reliance on Chromium. NodeGui wants to incorporate everything that is good about Electron: The ease of development, freedom of styling, Native APIs, great documentation, etc. At the same time NodeGui aims to be memory and CPU efficient.
Get started building with NodeGui in the [First NodeGui app](first-app.md).
### Updating Dependencies
When a new version of Node.js is released, NodeGui usually waits about a month before upgrading in order to bring in a more stable version.
NodeGui's version of Qt is usually updated within a month after a new stable version is released, depending on the effort involved in the upgrade.
### Versioning
NodeGui follows [`semver`](https://semver.org).
For most applications, and using any recent version of npm,
running `$ npm install @nodegui/nodegui` will do the right thing.
## Core Philosophy
In order to evolve faster with every Node.Js release, NodeGui aims to patch NodeJs with as much minimum code as possible. This makes sure we support all Node features and keeps upgrade process simple.
NodeGui will always link dynamically to Qt inorder to maintain LGPL lisence requirements for Open source projects.
NodeGui also encourages plugin/module based architecture, hence instead of bloating the entire core of NodeGui we prefer to build independent modules that can be managed and updated by the community thus keeping the end product binary size low and enabling faster upgrades.
extras/docs/tutorial/application-architecture.md
-104
View File
@@ -1,104 +0,0 @@
# NodeGui Application Architecture
Before we can dive into NodeGui's APIs, we need to discuss how NodeGui works internally. This would give a clear picture on why the APIs are the way they are.
## Qode
NodeGui uses Qt for creating Windows and other UI element. Hence it exports thin wrappers of native C++ widgets from Qt into Javascript world. Now, every Qt application needs to initialize an instance of `QApplication` before creating widgets. The way we do it in C++ Qt application is (dont worry if it doesnt make sense right now):
```cpp
#include <QApplication>
#include <QPushButton>
int main(int argc, char *argv[])
{
QApplication app(argc, argv); // Important
QPushButton hello("Hello world!");
hello.resize(100, 30);
hello.show();
return app.exec(); // Important
}
```
Like many Gui libraries Qt uses an event/message loop to handle events from widgets. Hence, when we call `app.exec()` Qt starts its message loop and blocks on that line. This is all good when there is only one message loop in the entire app. But since we want to use Qt with NodeJS and NodeJs has its own event loop, we cannot run both Qt and NodeJs on the same thread easily.
Then following questions arise:
- **What if we run Qt on a separate thread?** : No this is not possible since Qt has a requirement that it needs to run on the main thread.
- **What if we run Node on a separate thread?** : This would mean we need to build a complex bridge between Node and Qt threads to make them communicate. A strict no no.
So inorder to make both NodeJs and Qt work together we need to find a way to merge these two event loop into one. This is achieved by a custom NodeJs binary we call as `Qode`.
Qode is a lightly modified fork of Node.js that merges Node's event loop with Qt's event loop. The idea of merging event loops is inspired by Electron and [other](https://github.com/yue) Gui libraries developed by [zcbenz (Cheng Zhao)](https://github.com/zcbenz). It has been detailed in a post here: [Electron internals](https://electronjs.org/blog/electron-internals-node-integration). Hence, we reused the logic from electron to achieve smooth integration between Qt and NodeJs.
The idea is to release a corresponding Qode binary for every NodeJs version that comes out after Node v12.6.
The source code of Qode can be found [here](https://github.com/master-atul/qode).
_\*PS: Qode is a fork of [Yode](https://github.com/yue/yode)_
## Using NodeGui APIs
NodeGui offers a number of APIs that support the development of a desktop
application. You'd access NodeGui's APIs by requiring its included module:
```javascript
require("@nodegui/nodegui");
```
A window in NodeGui is for instance created using the `QMainWindow`
class.
```javascript
const { QMainWindow } = require("@nodegui/nodegui");
const win = new QMainWindow();
```
## Using Nodejs APIs
NodeGui exposes full access to Node.js. This has two important implications:
1. All APIs available in Node.js are available in NodeGui. Calling the
following code from an NodeGui app works:
```javascript
const fs = require("fs");
const root = fs.readdirSync("/");
// This will print all files at the root-level of the disk,
// either '/' or 'C:\'.
console.log(root);
```
2. You can use Node.js modules in your application. Pick your favorite npm
module. npm offers currently the world's biggest repository of open-source
code – the ability to use well-maintained and tested code that used to be
reserved for server applications is one of the key features of NodeGui.
As an example, to use the official AWS SDK in your application, you'd first
install it as a dependency:
```sh
npm install --save aws-sdk
```
Then, in your NodeGui app, require and use the module as if you were
building a Node.js application:
```javascript
// A ready-to-use S3 Client
const S3 = require("aws-sdk/clients/s3");
```
There is one important caveat: Native Node.js modules (that is, modules that
require compilation of native code before they can be used) will need to be
compiled with Qode or a compatible Node version to be used with NodeGui.
The vast majority of Node.js modules are _not_ native. Only 400 out of the
~650.000 modules are native. However, if you do need native modules, please
consult [this guide on how to recompile them for NodeGui][native-node].
[native-node]: ./using-native-node-modules.md
extras/docs/tutorial/development-environment.md
-89
View File
@@ -1,89 +0,0 @@
# Developer Environment
NodeGui development is essentially Node.js development. To turn your operating
system into an environment capable of building desktop apps with NodeGui,
you will merely need Node.js, npm, a code editor of your choice, and a
rudimentary understanding of your operating system's command line client.
## Setting up macOS
> NodeGui supports macOS 10.10 (Yosemite) and up. NodeGui currently only supports 64bit OS.
Currently supported Node.Js versions are 12.x and up.
We strongly suggest you use some kind of version manager for Node.Js. This would allow you to switch to any version of nodejs quite easily. We recommend `nvm`: https://github.com/nvm-sh/nvm
Confirm that both `node` and `npm` are available by running:
```sh
# This command should print the version of Node.js
node -v
# This command should print the version of npm
npm -v
```
If both commands printed a version number, you are all set! Before you get
started, you might want to install a [code editor](#a-good-editor) suited
for JavaScript development.
## Setting up Windows
> NodeGui supports Windows 7 and later versions – attempting to develop NodeGui
> applications on earlier versions of Windows might not work. NodeGui currently only supports 64bit OS.
Currently supported Node.Js versions are 12.x and up.
We strongly suggest you use some kind of version manager for Node.Js. This would allow you to switch to any version of nodejs quite easily. We recommend `nvm`: https://github.com/nvm-sh/nvm
We strongly recommend Powershell as preferred terminal in Windows.
Confirm that both `node` and `npm` are available by running:
```powershell
# This command should print the version of Node.js
node -v
# This command should print the version of npm
npm -v
```
If both commands printed a version number, you are all set! Before you get
started, you might want to install a [code editor](#a-good-editor) suited
for JavaScript development.
## Setting up Linux
> NodeGui currently supports Ubuntu 12.04 and Debian 8 and up. Although other linux distributions can also be easily supported. NodeGui currently only supports 64bit OS.
Currently supported Node.Js versions are 12.x and up.
We strongly suggest you use some kind of version manager for Node.Js. This would allow you to switch to any version of nodejs quite easily. We recommend `nvm`: https://github.com/nvm-sh/nvm
We strongly recommend Powershell as preferred terminal in Windows.
Confirm that both `node` and `npm` are available by running:
```sh
# This command should print the version of Node.js
node -v
# This command should print the version of npm
npm -v
```
If both commands printed a version number, you are all set! Before you get
started, you might want to install a [code editor](#a-good-editor) suited
for JavaScript development.
## A Good Editor
We might suggest two free popular editors built in NodeGui:
GitHub's [Atom][atom] and Microsoft's [Visual Studio Code][code]. Both of
them have excellent JavaScript support.
If you are one of the many developers with a strong preference, know that
virtually all code editors and IDEs these days support JavaScript.
[code]: https://code.visualstudio.com/
[atom]: https://atom.io/
extras/docs/tutorial/first-app.md
-117
View File
@@ -1,117 +0,0 @@
# Writing Your First NodeGui App
NodeGui enables you to create desktop applications with pure JavaScript. You could see it
as a lightly modified variant of the Node.js runtime that is focused on desktop applications
instead of web servers.
NodeGui is also an efficient JavaScript binding to a cross platform graphical user interface
(GUI) library `Qt`. Qt is one of the most mature and efficient library for building desktop applications.
This enabled NodeGui to be extrememly memory and CPU efficient as compared to other popular Javascript Desktop GUI solutions. A hello world app built with NodeGui runs on less than 20Mb of memory.
## Hello World
Clone and run the code in this tutorial by using the
[`nodegui/nodegui-starter`][quick-start] repository.
**Note**: Running this requires [Git](https://git-scm.com) and [npm](https://www.npmjs.com/).
```sh
# Clone the repository
$ git clone https://github.com/nodegui/nodegui-starter
# Go into the repository
$ cd nodegui-starter
# Install dependencies
$ npm install
# Run the app
$ npm start
```
As far as development is concerned, an NodeGui application is essentially a
Node.js application. The starting point is a `package.json` that is identical
to that of a Node.js module. A most basic NodeGui app would have the following
folder structure:
```text
your-app/
├── package.json
├── index.js
```
## NodeGui Development in a Nutshell
NodeGui apps are developed in JavaScript using the same principles and methods
found in Node.js development. All APIs and features found in NodeGui are
accessible through the `@nodegui/nodegui` module, which can be required like any other
Node.js module:
```javascript
require("@nodegui/nodegui");
```
The `@nodegui/nodegui` module exports features in namespaces. As examples, windows can be created
using the `QMainWindow` class. A simple `main.js` file might open a window:
```javascript
const {
QMainWindow,
QWidget,
QLabel,
FlexLayout
} = require("@nodegui/nodegui");
const win = new QMainWindow();
//-------------------------------
const centralWidget = new QWidget();
centralWidget.setObjectName("myroot");
const rootLayout = new FlexLayout();
centralWidget.setLayout(rootLayout);
//--------------------------------------
const label = new QLabel();
label.setObjectName("mylabel");
label.setText("Hello World");
//--------------------------------------
rootLayout.addWidget(label);
win.setCentralWidget(centralWidget);
win.setStyleSheet(
`
#myroot {
background-color: #009688;
}
#mylabel {
font-size: 16px;
font-weight: bold;
}
`
);
win.show();
global.win = win; // To prevent win from being garbage collected.
```
The `index.js` should create windows and handle all the system events your
application might encounter.
## Running Your App
You can try your app by running `npm start` from your application's
directory.
## Trying this Example
Clone and run the code in this tutorial by using the
[`nodegui/nodegui-starter`][quick-start] repository.
**Note**: Running this requires [Git](https://git-scm.com) and [npm](https://www.npmjs.com/).
```sh
# Clone the repository
$ git clone https://github.com/nodegui/nodegui-starter
# Go into the repository
$ cd nodegui-starter
# Install dependencies
$ npm install
# Run the app
$ npm start
```
[quick-start]: https://github.com/nodegui/nodegui-starter
extras/docs/tutorial/support.md
-34
View File
@@ -1,34 +0,0 @@
# NodeGui Support
## Finding Support
If you're looking for programming help or for answers to questions please file an issue on the NodeGui's Github project issues and we will try our best to answer and help out.
## Supported Platforms
Following platforms are supported by NodeGui:
### macOS
Only 64bit binaries are provided for macOS, and the minimum macOS version
supported is macOS 10.10 (Yosemite).
### Windows
Windows 7 and later are supported, older operating systems are not supported
(and might not work).
Only `x64` (`amd64`) binaries are provided for Windows at this point of time.
### Linux
The prebuilt `x64` (`amd64`) binaries of NodeGui are built on Ubuntu 12.04.
Whether the prebuilt binary can run on a distribution depends on whether the
distribution includes the libraries that NodeGui is linked to on the building
platform, so only Ubuntu 12.04 is guaranteed to work, but following platforms
are also verified to be able to run the prebuilt binaries of NodeGui:
- Ubuntu 12.04 and newer
- Fedora 21
- Debian 8
extras/docs/tutorial/using-native-node-modules.md
-52
View File
@@ -1,52 +0,0 @@
# Using Native Node Modules
Native Node modules are supported by NodeGui, but since NodeGui is very
likely to use a different V8 version from the Node binary installed on your
system, the modules you use will need to be recompiled for NodeGui's node/v8 version. Otherwise,
you will get the following class of error when you try to run your app:
```sh
Error: The module '/path/to/native/module.node'
was compiled against a different Node.js version using
NODE_MODULE_VERSION $XYZ. This version of Node.js requires
NODE_MODULE_VERSION $ABC. Please try re-compiling or re-installing
the module (for instance, using `npm rebuild` or `npm install`).
```
## How to install native modules
To compile native Node modules against a build of NodeGui that doesn't
match a public release, instruct `npm` to use the version of Qode (NodeJs) you have bundled
with your custom build.
```sh
npm rebuild --nodedir=/path/to/nodegui/vendor/qode
```
or
```sh
qode /path/to/npm rebuild
```
## Troubleshooting
If you installed a native module and found it was not working, you need to check
the following things:
- When in doubt, rebuild native modules with qode first.
- Make sure the native module is compatible with the target platform and
architecture for your NodeGui app.
- After you upgrade NodeGui, you usually need to rebuild the modules.
## Modules that rely on `node-pre-gyp`
The [`node-pre-gyp` tool][node-pre-gyp] provides a way to deploy native Node
modules with prebuilt binaries, and many popular modules are using it.
Usually those modules work fine under NodeGui, but sometimes when NodeGui uses
a newer version of V8 than Node and/or there are ABI changes, bad things may
happen. So in general, it is recommended to always build native modules from
source code.
[node-pre-gyp]: https://github.com/mapbox/node-pre-gyp