Skip to content

Icestudio development version

Jump to bottom
Carlos Venegas Arrabé edited this page May 16, 2024 · 81 revisions

Contents

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 --legacy-peer-deps

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 --legacy-peer-deps

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
preptext npm run preptext preptext -- 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$

Preptext

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 preptext

> [email protected] preptext
> grunt preptext

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

Home Page

Getting started

Collections

  • Default: Icestudio Default Collection

Stable

Development

  • IceBoards: blocks and examples for the diferent FPGA boards
  • IceComp: Comparators
  • IceArith: Integer arithmetics
  • IceCounter: Counters
  • IceSignals: 1-bit signal managment
  • IcePLL: PLLs
  • IceLEDOscope: Measuring signals
  • IceLEDs: Displaying on LEDs
  • IceHearts: Timming signal generation
  • IceInputs: 1-bit inputs
  • IceRok: Block probes for Icestudio => Sigrok integration (with Pulseview GUI)
  • IceMachines: Working with Machines (simple state machines with a standar interface)
  • IceSerial: Serial Asynchronous communications
  • IceMem: Working with Memories
  • IceMeasure: Measuring cycles and time in your circuits, very easily
  • IceStack: Working with stacks
  • IceFlash: Read from spi serial flash memories
  • IceBus: Accesing and sharing simple buses
  • IceLCD: Components and controllers for LCDs
  • IceUnary: Working with unary numbers
  • IceCrystal: Drive displays from Open Source FPGAs
  • ice-chips-verilog: IceChips is a library of all common discrete logic devices in Verilog
  • ArithmeticBlocks: FPGA signed and unsigned integer operations, 16, 24 and 32 bits, + - * / sqrt min max compare etc.
  • iceSynth: Audio synthesis
  • icebreaker: Blocks and examples for the icebreaker OpenFPGA board
  • Jedi: blocks of the FPGA Jedi hardware Academy
  • LOVE-FPGA: Hardware elements and examples for the LOVE-FPGA project (Linking Of Virtual Electronics to FPGAs)
  • Stdio: Standard Input-Output in different devices
  • CT11: Ejemplos del cuaderno ténico 11: Señales del sistema y Medición con el LEDOscopio
  • Generic: Icestudio Generic Collection
  • Logic: Icestudio Logic Collection
  • IceInterface: Serial, SPI, I2C... (TODO)

Testbenches

Developers

Contribute

HELP

Release history

Clone this wiki locally