You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Packaging: Edit README to link to wiki documentation
Also updates the requirements.txt file for the Python build scripts
dependencies.
Removed the TODO list as it has been moved to the Wiki documentation.
The package folder contains the Python scripts required to package Ardublockly into a standalone executable. This way it can be distributed without any dependencies other than having the Arduino IDE.
2
+
This package folder contains three components required to build and package the Ardublockly desktop application:
3
3
4
-
The application can be categorised in three main components: Python server, HTML/Javascript front end, and a desktop application wrapper.
5
-
6
-
Currently the Python server is packaged using py2exe for Windows, and PyInstaller for Linux and Mac OS X. In the future PyInstaller might be updated to also create the Windows builds, for now the original py2exe script is pretty stable.
7
-
8
-
The desktop wrapper is based on Electron, which uses node.js. The node.js component is only used where required for the application to integrate well with the individual desktop platforms. Originally the Chromium Embedded Framework Python bindings were used, but cross-platform maintenance proved to be problematic and Electron has provided a much smother alternative.
4
+
*The [Electron][1] project to use Ardublockly as a desktop application
5
+
* Python scripts required to build and package Ardublockly into a standalone executable.
6
+
* Git submodule that contains the documentation (stored in the Ardublockly GitHub Wiki)
7
+
8
+
The full build instruction can be found in the Ardublockly GitHub Wiki article [Building-Ardublockly][2].
9
9
10
+
The build output can be distributed without any dependencies other than having the Arduino IDE.
10
11
11
12
## Download the packaged Ardublockly
12
13
The stable binaries for Windows, Linux, and Mac OS X are hosted in GitHub as part of the [repository releases][1].
@@ -19,150 +20,8 @@ Development builds are triggered in the CI build servers on each git commit and
Git needs to be installed on the system and accessible through the command line interface.
26
-
27
-
28
-
### Python
29
-
These build scripts have been developed and tested only on Python 2.7.
30
-
31
-
While the non-GUI version of Ardublockly (command line server + browser-based GUI) is compatible with other Python versions (tested on Python 2.7 and 3.4), due to the individual perks of the python libraries used here and initial unavailability of some Python 3 bindings, a single build environment based on Python 2.7 has been be targeted.
32
-
33
-
If you are using Python virtual environments on Windows this [collection of Python extensions binaries][2] is highly recommended.
34
-
35
-
The specific versions of the Python dependencies can be found in the [requirements.txt][3] file.
36
-
37
-
##### py2exe
38
-
py2exe is a Distutils extension to build Python scripts into Windows executable programs.
39
-
40
-
This package is only required for the Windows build. The Linux and Mac OS X builds use the PyInstaller scripts included in this folder.
41
-
42
-
You can download py2exe from their [official website][4].
43
-
44
-
##### PyInstaller
45
-
Converts (packages) Python programs into stand-alone executables, used for the Linux and Mac OS X builds.
46
-
47
-
[PyInstaller][5] can be easily installed using pip:
48
-
49
-
```
50
-
pip install pyinstaller
51
-
```
52
-
53
-
##### MkDocs
54
-
[MkDocs][6] is a static page generator specifically designed for documentation using Markdown.
55
-
56
-
The project documentation is written and hosted in the [Ardublockly GitHub Wiki][7]. The build script for the documentation pulls its markdown files and converts them into an HTML static site for offline access.
57
-
58
-
More information about this procedure can be found on [this article][8].
59
-
60
-
MkDocs can be easily installed using pip:
61
-
62
-
```
63
-
pip install MkDocs
64
-
```
65
-
66
-
### Node.js
67
-
Node.js is required to run [Electron][9]. It can be downloaded from the [official website][10].
68
-
69
-
The `npm` package manager should be included with node, which is used to deal with all the Electron application dependencies.
If you have already downloaded the Ardublockly source code, make sure the submodules are initialised, in this case the 'closure-library' in the project root directory, and 'ardublockly.wiki' in the 'package/ardublocklydocs/' folder. You can run the last git command above in the project root directory to ensure this is the case, otherwise the submodules directories will be empty.
82
-
83
-
### First step: Python server (platform dependent)
84
-
85
-
The build steps for the Ardublockly Server are slightly different depending on the platform.
86
-
87
-
### Windows Build
88
-
To build Ardublockly under Windows all you have to do is execute the `build_windows.py` file from the project root directory:
89
-
90
-
```
91
-
python package\build_windows.py
92
-
```
93
-
94
-
This will remove any previous build directory, rebuild, and create the `ardublockly_run.bat` file into the project root.
95
-
96
-
### Linux Build
97
-
To build Ardublockly under Linux all you have to do is execute the `build_pyinstaller.py` file from the project root directory:
98
-
99
-
```
100
-
python package/build_pyinstaller.py
101
-
```
102
-
103
-
The optional flag `linux` can be provided, but the operating systems should be automatically detected.
104
-
105
-
This will remove any previous build directory, rebuild, and create the `ardublockly_run.sh` file into the project root.
106
-
107
-
### Mac OS X Build
108
-
To build Ardublockly under Mac OS X all you have to do is execute the `build_pyinstaller.py` file from the project root directory:
109
-
110
-
```
111
-
python package/build_pyinstaller.py
112
-
```
113
-
114
-
The optional flag `mac` can be provided, but the operating systems should be automatically detected.
115
-
116
-
This will remove any previous build directory, and rebuild it.
117
-
118
-
119
-
## Second step: Electron (platform independent)
120
-
Execute the following commands from the project root directory:
121
-
122
-
```
123
-
cd package\electron
124
-
npm install
125
-
npm run release
126
-
```
127
-
128
-
The npm scripts will automatically detect and deal with the operating system different build requirements.
129
-
130
-
At this point, if continuing with the next steps, is recommended to go back to the project root directory:
131
-
132
-
```
133
-
cd ../../
134
-
```
135
-
136
-
## Third step: Documentation (platform independent)
137
-
138
-
Build the offline documentation by running the `build_docs.py` script from the project root directory:
139
-
140
-
```
141
-
python package\build_docs.py
142
-
```
143
-
144
-
This will remove any previous build directory, rebuild it, and remove any temporary files.
145
-
146
-
## Final Step: Packing all Ardublockly (platform independent)
147
-
This step is only meant if you wish to pack the Ardublockly application into a distributable form. You can pack ardublockly running the following command from the project root directory:
148
-
149
-
```
150
-
python package/pack_ardublockly.py
151
-
```
152
-
153
-
The pack script is designed for the build servers to zip the required contents into a single file to be uploaded to cloud storage, so it still leaves quite a few things behind. This script creates a new folder on the same level a the project root, and then zips it and saves it into the folder 'upload' within the project root.
0 commit comments