Icestudio development version

Contents

• Introduction
• Running the development version
  • Ubuntu-linux-22.04
  • Windows
  • MACOS
• NPM targets
  • Install
  • Postinstall
  • Start: Run Icestudio
  • Getcollection: Download and install the default collection
  • Clean
  • jshit: Checking .js files
  • Gettext
  • Compiletext
  • Build{platform}
    • Example: Building the linux package
    • Grunt tasks

Introduction

The latest development icestudio can be found in the develop branch (it is the default branch when you clone it)

Running the development version

Ubuntu Linux 22.04

Follow these steps:

Installing dependencies

For running icestudio you need to install node 19.3.0. You can install it very easily with the Node Version manager tool (nvm)

• Install nvm:

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash

• Close the terminal and open it again. Nvm will be now ready
• Install node 19.3.0:

nvm install 19.3.0

• Print the node version for checking that everything is ok:

$ node -v
v19.3.0

Clone the icestudio repo

git clone https://github.com/FPGAwars/icestudio.git

Install the node dependencies

• Enter into the icestudio folder

cd icestudio

• Install the node dependencies:

npm install

Run icestudio develop

Just type this command and icestudio will show up:

npm start

or you can start it directly running the nw binary:

./node_modules/nw/bin/nw app

Windows 10

Installing dependencies

For running icestudio you need to install node 19.3.0. In this link you will find the node 19.3.0 installers for different operating systems. Or, if you prefer, installing the Node Version Manager (nvm) for Windows is also a good option

Once installed, make sure it is the correct version. Open a command line console (cmd) and type node --version:

Also you need to install git

Clone the icestudio repo

git clone https://github.com/FPGAwars/icestudio.git

Install the node dependencies

• Enter into the icestudio folder

cd icestudio

• Install the node dependencies:

npm install

Run icestudio develop

Just type this command and icestudio will show up:

npm start

MAC

TODO

NPM targets

This is the list of implemented NPM commands. They all are implemented by calling the corresponding grunt task

Target	Command	Grunt task	Grunt argument	Description
install	npm install	--	--	Install the icestudio dependencies. The postinstall target is execute after the installation
postinstall	npm run postinstall	--	--	Download the default collection, install the platform dependencies and execute npm install on the Icestudio app folder
start	npm start	serve	--	Start icestudio (in developer mode)
getcollection	npm run getcollection	getcollection	--	Download the Default collection
clean	npm run clean	clean	--	Clean the temporary folders
jshint	npm run jshint	jshint	--	Check all the javascript (.js) files
gettext	npm run gettext	gettext	--	Extract the English texts to the template.pot file
compiletext	npm run compiletext	compiletext	--	Compile the po files into json format
buildLinux64	npm run buildLinux64	dist	--platform=linux64	Build executable Icestudio package por Linux 64-bits
buildAarch64	npm run buildAarch64	dist	--platform=aarch64	Build executable Icestudio package for ARM 64-bits
buildWindows	npm run buildWindows	dist	--platform=win64	Build executable Icestudio package for Windows 64-bits
buildOSX	npm run buildOSX	dist	--platform=darwin	Build executable Icestudio package for MAC 64-bits

Install

Once you start from a fresh cloned Icestudio repo, you need to install the dependencies by running the npm install command. After the installation, the postinstall script is executed

The top level npm install install all the packages describe in the icestudio/package.json file. The main package is Grunt. It is used for automating purposes. It is not part of the final Icestudio distribution package. After the installation, the postinstall target is executed, where the rest of icestudio dependencies are installed. The Icestudio application is located in the folder app (see the next section)

Postinstall

The postinstall target is executed automatically after the command npm install in the Icestudio root repo folder. It performs the following actions:

• Download the Icestudio default collection and install it under icestudio/app/resources/collection
• Install the Platform dependencies. The tool npmpd from the npm-platform-dependencies package is installed. It installs all the packages needed for a specific platform (For example the package grunt-appdmg for MAC)
• Enter into the icestudio/app folder
• Install all the icestudio dependencies. The command npm install is executed in the folder icestudio/app. The Icestudio dependencies can be found on the icestudio/app/package.json file

Start: Run Icestudio

For launching icestudio in development mode, execute the following command: npm start

obijuan@Hoth:~/Develop/FPGAwars/icestudio$ npm start

> [email protected] start
> grunt serve

Executing Gruntfile.js...

------------ INFORMATION FOR DEBUGING -------------------
* Package name: icestudio-0.9.1w202203201003
* NW Version: 0.58.0
* APPIMAGE: dist/icestudio-0.9.1w202203201003-linux64.AppImage
* DMGIMAGE: dist/icestudio-0.9.1w202203201003-osx64.dmg
* Target platform: linux64
* SubTASK for the DIST task:
┌─────────┬─────────────────────┐
│ (index) │       Values        │
├─────────┼─────────────────────┤
│    0    │      'jshint'       │
│    1    │    'clean:dist'     │
│    2    │ 'nggettext_compile' │
│    3    │     'copy:dist'     │
│    4    │    'json-minify'    │
│    5    │       'nwjs'        │
│    6    │ 'compress:linux64'  │
│    7    │ 'appimage:linux64'  │
│    8    │     'clean:tmp'     │
└─────────┴─────────────────────┘

Running "nggettext_compile:all" (nggettext_compile) task

Running "watch:scripts" (watch) task
Waiting...

---------------------------------------------------------
Running "exec:stopNW" (exec) task

Running "exec:nw" (exec) task
>> Error: unrecognized flag --no-untrusted-code-mitigations
>> The remaining arguments were ignored: --allow_natives_syntax
>> Try --help for options
>> [13280:13365:0320/102817.096927:ERROR:chrome_browser_main_extra_parts_metrics.cc(230)] crbug.com/1216328: Checking Bluetooth availability started. Please report if there is no report that this ends.
>> [13280:13365:0320/102817.096965:ERROR:chrome_browser_main_extra_parts_metrics.cc(233)] crbug.com/1216328: Checking Bluetooth availability ended.
>> [13280:13365:0320/102817.096974:ERROR:chrome_browser_main_extra_parts_metrics.cc(236)] crbug.com/1216328: Checking default browser status started. Please report if there is no report that this ends.
>> [13280:13365:0320/102817.153762:ERROR:chrome_browser_main_extra_parts_metrics.cc(240)] crbug.com/1216328: Checking default browser status ended.
>> [13312:13321:0320/102913.143649:ERROR:cert_verify_proc_builtin.cc(600)] No net_fetcher for performing AIA chasing.
>> [13312:13582:0320/102913.144868:ERROR:cert_verify_proc_builtin.cc(600)] No net_fetcher for performing AIA chasing.

You will see many debug information on the console and then the ICestudio start window will show up

There are two grunt task executed before starting Icestudio:

• nggettext_compile: It compiles all the .po files into JSON. These json files are read by Icestudio
• watch: When any src file is modified, Icestudio is launched again automatically (you do not need to start manually on every change)

Getcollection: Download and install the default collection

The Default collection is downloaded and installed on the app/resources/collection folder. It is automatically done after the installation with npm install or can be executed manually with the command npm run getcollection

obijuan@Hoth:~/Develop/FPGAwars/icestudio$ npm run getcollection

> [email protected] getcollection
> grunt getcollection

Executing Gruntfile.js...
[...]

Running "clean:collection" (clean) task
>> 1 path cleaned.

Running "wget:collection" (wget) task

Running "unzip:using-router" (unzip) task
Created "app/resources" directory

Done.

Clean

Clean the temporary folders:

• dist/tmp
• dist
• app/resources/collection;

This task is executed by means of this command: npm run clean

obijuan@Hoth:~/Develop/FPGAwars/icestudio$ npm run clean

> [email protected] clean
> grunt clean

Executing Gruntfile.js...
[...]
---------------------------------------------------------
Running "clean:tmp" (clean) task
>> 0 paths cleaned.

Running "clean:dist" (clean) task
>> 1 path cleaned.

Running "clean:collection" (clean) task
>> 1 path cleaned.

Done.

jshint: Checking js files

The npm run jshint command should be executed before any commit to the develop branch. It gurantees that the javascript files have no errors and code style is correct

Here you can see the typical output:

obijuan@Hoth:~/Develop/FPGAwars/icestudio$ npm run jshint

> [email protected] jshint
> grunt jshint

Executing Gruntfile.js...
Icestudio package name: icestudio-0.9.1w202203141003
Running "jshint:all" (jshint) task
>> 28 files lint free.

Done.
obijuan@Hoth:~/Develop/FPGAwars/icestudio$

Gettext

This target extracts the English texts to be translated and stores them into the file app/resources/locale/template.pot

obijuan@Hoth:~/Develop/FPGAwars/icestudio$ npm run gettext

> [email protected] gettext
> grunt gettext

Executing Gruntfile.js...
[...]
---------------------------------------------------------
Running "nggettext_extract:pot" (nggettext_extract) task

Done.

Compiletext

This target converts the .po files (with the translations) to .json files. These files are loctated in the folder app/resources/locale/{locale}, where {locale} is the locale name (For example, es_ES for the Spanish translation)

obijuan@Hoth:~/Develop/FPGAwars/icestudio$ npm run compiletext

> [email protected] compiletext
> grunt compiletext

Executing Gruntfile.js...
[...]
---------------------------------------------------------
Running "nggettext_compile:all" (nggettext_compile) task

Done.

The corresponding JSON file is loaded by Icestudio during the start-up

Build{plaform}

The build targets create the final Icestudio package/executable for the users of the diffent platforms. There are four targets:

• buildLinux64: For Linux 64-bits
• buildAarch64: For ARM-linux 64-bits
• buildWindows: For Windows 64-bits
• buildOSX: For MAX-64bits

The binaries for the Linux, windows and MAC are created with the nw-builder package. The package for ARM is created differently, first building for Linux and then adding manually the NWjs binaries for ARM.

When the corresponding target is executed, the icestudio binaries for that platform are built and stored in the dist folder

Example: building the Linux package

For generating the Icestudio package for Linux execute this command: npm run buildLinux64

obijuan@Hoth:~/Develop/FPGAwars/icestudio$ npm run buildLinux64

> [email protected] buildLinux64
> grunt dist --platform=linux64

Executing Gruntfile.js...

------------ INFORMATION FOR DEBUGING -------------------
* Package name: icestudio-0.9.1w202203201203
* NW Version: 0.58.0
* APPIMAGE: dist/icestudio-0.9.1w202203201203-linux64.AppImage
* DMGIMAGE: dist/icestudio-0.9.1w202203201203-osx64.dmg
* Target platform: linux64
* SubTASK for the DIST task:
┌─────────┬─────────────────────┐
│ (index) │       Values        │
├─────────┼─────────────────────┤
│    0    │      'jshint'       │
│    1    │    'clean:dist'     │
│    2    │ 'nggettext_compile' │
│    3    │     'copy:dist'     │
│    4    │    'json-minify'    │
│    5    │       'nwjs'        │
│    6    │ 'compress:linux64'  │
│    7    │ 'appimage:linux64'  │
│    8    │     'clean:tmp'     │
└─────────┴─────────────────────┘
---------------------------------------------------------
Running "jshint:all" (jshint) task
>> 28 files lint free.

Running "clean:dist" (clean) task
>> 1 path cleaned.

Running "nggettext_compile:all" (nggettext_compile) task

Running "copy:dist" (copy) task
Created 971 directories, copied 11955 files

Running "json-minify:json" (json-minify) task

Total compressed: 188 files
>> 521.88 KiB - 7% = 485.226 KiB

Running "json-minify:ice" (json-minify) task

Total compressed: 0 files
>> 0 KiB - 0% = 0 KiB

Running "nwjs:src" (nwjs) task
Using v0.58.0 (sdk)
Create cache folder in /home/obijuan/Develop/FPGAwars/icestudio/cache/0.58.0-sdk
Using cache for: linux64
Create release folder in /home/obijuan/Develop/FPGAwars/icestudio/dist/icestudio/linux64
>> NW.js app created.

Running "compress:linux64" (compress) task
>> Compressed 13075 files.

Running "appimage:linux64" (appimage) task
>> File "dist/icestudio-0.9.1w202203201203-linux64.AppImage" created.

Running "clean:tmp" (clean) task
>> 1 path cleaned.

Done.

When all the tasks are finished, the package icestudio-0.9.1w202203201203-linux64.AppImage is ready in the dist folder

Grunt tasks

For building the packages there are tasks common to all the platforms, and taks specific to a platform

These are the common taks:

• jshint: Check the js files
• clean:dist: Delete the dist folder
• nggettext_compile: Extract English texts to the template file
• copy:dist: Copy the files to be included in the build package
• json-minify: Minify JSON files
• nwjs: Build the executable package

These are the specific tasks:

• linux64:
  • compress:linux64: Create the Icestudio zip package
  • appimage:linux64, Create the Icestudio appimage package
• win64:
  • compress:win64": Create the Icestudio zip package
  • wget:python64: Download the python package for windows
  • exec:nsis64: Build the Windows installer
• osx64:
  • exec:repairOSX: Execute a script for MAC
  • compress:osx64: Create the Icestudio .zip package
  • appdmg: Build the Icestudio appmdg package
• aarch64:
  • wget:nwjsAarch64: Download the ARM NW dist Tarball
  • copy:aarch64: Copy the Linux build dir to ARM build dir
  • shell:mergeAarch64: Untar the NW binary files and merge them in the build dir",
  • compress:Aarch64: Build the final .zip file

---