Table of Contents

License 

HOP, a web development kit - copyright (c) 2006-2024 INRIA
                                                                 
Bug descriptions, user reports, comments, suggestions and
pull requests are welcome. Send them to
   https://github.com/manuel-serrano/hop.git

Hop comes with three different license versions, which should be
specified when configuring Hop and that come with three different
permission of use:

 - free: no restriction of any kind.
 - academic: reserved exclusively to academic use (research and teaching).
 - commercial: no restriction but needs the Inria approval first.
 
The optimizing compiler is only availabe with academic and commercial
versions.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by 
the Free Software Foundation; either version 2 of the License, or 
(at your option) any later version. More precisely:

 The server, the compiler, and the tools are distributed under the 
 terms of the GNU General Public License.

This program is distributed in the hope that it will be useful,   
but WITHOUT ANY WARRANTY; without even the implied warranty of    
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the     
GNU General Public License for more details.                      
                                                                  
You should have received a copy of the GNU General Public         
License along with this program; if not, write to the Free        
Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,   
MA 02111-1307, USA.

See License Academic for details about the academic license.

Binary distributions

Precompiled Hop.js distributions are available.

Debian/Raspberry

A repository is available. To use it, add the following to your apt path:

echo 'deb http://hop.inria.fr/linux/Debian bullseye hop' | sudo tee /etc/apt/sources.list.d/hop.list
curl http://www-sop.inria.fr/members/Manuel.Serrano/serrano.pkey | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/hop.gpg > /dev/null
sudo apt update
sudo apt install hop

The Debian packages are all installed in the /opt/hop directory so you will probably need to modify the PATH variable accordingly:

export PATH=/opt/hop/bin:$PATH

Ubuntu

An Ubuntu repository is available. To use it, add the following to your apt path:

echo 'deb http://hop.inria.fr/linux/Ubuntu jammy hop' | sudo tee /etc/apt/sources.list.d/hop
curl http://www-sop.inria.fr/members/Manuel.Serrano/serrano.pkey | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/hop.gpg

The Ubuntu packages are all installed in the /opt/hop directory. See below.

Homebrew

Homebrew users (MacOS X), can use the pre-built version by using:

$ brew tap homebrew/hop https://gitlab.inria.fr/mserrano/hopbrew.git
$ brew install homebrew/hop/bigloo-latest

Source code installation

This is the file you should download if you want to build the Hop stable version from the sources.

Compiling Hop.js requires the Bigloo compiler.

Bigloo installation

To configure and install the Bigloo compiler that is needed to compile Hop, use the following:

$ ./configure --abort-missing && make && sudo make install

Hop installation

To configure and install Hop, execute the following:

$ ./configure && make && sudo make install

Optionally, to compile and install the documentation:

$ make doc && sudo make install

To test the installation:

$ make test

Docker installation

The recommanded way to install and run Hop is to use Docker. Download the hop-3.6.0.dockerfile script and execute the following command to generate the Docker image: 

docker build -f hop-${cfg.version}.dockerfile -t hop .

Note: If you already have installed Hop within docker, you might find useful to remove the old image first. This can be achieved with:

$ docker container prune
$ docker rmi `docker images | grep hop | awk '{print $3}'`

Running Hop with Docker

How to run Hop inside docker depends on the Host platform and the local Docker configuration. In particular, the mapping between Docker network interfaces and the host network interfaces is system dependant. With Linux and MacOSX, Hop inside Docker should be accessible via localhost. On Windows, it might be needed to use the IP address generated automatically when its daemon is started.

The bash script hop-3.6.0.docker makes running Hop inside Docker almost as simple as running it natively as it automatically associates the host disk and the Docker image disk as needed by the Hop application. For instance, it can be used as:

$ mkdir -p $HOME/.config/hop
$ cat > $HOME/.config/hop/hoprc.js << EOF
hop = require( "hop" );
var user = require( hop.user );
user.add( { name: "anonymous", services: "*", directories: "*" } );
EOF
$ cat > /tmp/hello.js << EOF
console.log( "Hello World!" );

service hello() {
  return Hello World!'
}
EOF
$ hop-${cfg.version}.docker -p 8888 /tmp/hello.js
$ firefox http://localhost:8888/hop/hello

Note: On Windows, hop-3.6.0.docker has to be executed from within the Bash shell script spawned by Docker.

The hop3.6.0.docker file is shipped with the Docker image. In addition to be downloaded from the Hop ftp repository, it can be copied to the local disk with:

docker cp hop:/usr/local/share/hop/${cfg.branch}/hop.docker .

Accessing the documentation and the Emacs mode

The complete Hop documentation is embedded inside the Docker image in the directory:

/usr/local/share/doc/hop/3.6.0

It can be copied to the host disk with:

docker cp hop:/usr/local/share/doc/hop/${cfg.branch} .

It can also be accessed via Hop. For instance, on a Linux host, if Hop is executed with

hop.docker -p 9999

the documentation could be access at the URL:

http://localhost:9999/usr/local/share/doc/hop/3.6.0/index.html

The Emacs mode can be copied to the host disk with:

docker cp hop:/usr/local/share/hop/site-lisp/hopjs.el .

Git

Hop.js can be forked at

https://github.com/manuel-serrano/hop.git

Older releases

Old Hop releases can be obtain at the following address:

ftp://ftp-sop.inria.fr/indes/fp/Hop/

Complete Installation Guide

### Prerequisites ###

The Hop system requires at a minimum a Linux or OSX environment and the standard suite of compilation tools.

We recommend that you also install the following additional tools using your prefered package manager in order to get best results during the automatic configuration phase of bigloo and hop software:

At configuration time, the system checks the availability of additional libraries. Supported libraries include:

Prerequisites for OSX

Hop.js 3.0.x is supported on recent versions of OSX, including Yosemite (10.10) and El Capitan (10.11), and may also work on older OS versions.

A convenient way to install the above tools and libraries on OSX is to use macports. See https://www.macports.org to install and use macports. Once macports is installed, you may for example install openssl simply by typing: sudo port install openssl

We recommend that you install the following packages (some of them are required to get full functionality or enhanced compatibility with Node.js):

Important notice: the openssl version shiped with OSX is too old and deprecated by Apple, please install openssl 1.0.2 or a newer version.

Macports

Tools and libs installed using macports are located in /opt/local/{bin,lib}. Macports updates the PATH environment variable to look for executable files into /opt/local/bin but does not change other env. variables. You must set C_INCLUDE_PATH and LIBRARY_PATH in your .profile file in order for the bigloo autoconfiguration tool to detect and use libraries installed in /opt/local.

export C_INCLUDE_PATH=/opt/local/include 
export LIBRARY_PATH=/opt/local/lib

Some of the installed libraries come with a pkg-config support file. Add this directory to PKG_CONFIG_PATH, again to have the autocofiguration tool work as expected.

export PKG_CONFIG_PATH=/opt/local/lib/pkgconfig:/usr/lib/pkgconfig
Brew

The setting for brew is

export C_INCLUDE_PATH=$(brew --prefix)/opt/openssl/include:$C_INCLUDE_PATH
export LIBRARY_PATH=$(brew --prefix)/opt/openssl/lib:$LIBRARY_PATH
export PKG_CONFIG_PATH=$(brew --prefix)/opt/openssl/lib/pkgconfig
Other package systems

If you use another package manager such fink, or if you install libraries from sources, please change above paths and install commands accordingly.

Install bigloo

Hop.js requires that bigloo (a scheme compiler and runtime) is installed on the target machine. bigloo can be downloaded from ftp://ftp-sop.inria.fr/indes/fp/Bigloo/bigloo4.3c.tar.gz (or a newer version).

tar xvf bigloo4.3c.tar.gz

and cd to the build directory (bigloo4.3c) .

Run the configure script:

./configure

Result of the automatic configuration script is logged in the file configure.log . You may find there the list of libraries that were found and bigloo configuration parameters. The default installation path is /usr/local/{lib,bin,...}. It can be overhidden with the --prefix option :

./configure --prefix=<custom_installation_path>

Other configuration options are listed by typing:

./configure --help

then run

 make

(or make -j to run build tasks in parallel on multicore machines)

At last run

 make install

or sudo make install

depending on your access rights on the installation directory.

Install hop

Untar the hop archive into a fresh directory and cd to the root directory. Run the configure script:

./configure

The --prefix option works as usual to set a custom <install-prefix> (default is /usr/local).

An other interesting option is:

--bigloo=<bigloo_path> to specify a specific bigloo executable to be used by hop. The default value will retrieve bigloo in the user PATH.

./configure --help

to see all available options. Once the configuration is completed, run :

 make # or make -j

then run

 make install # or  sudo make install

Test the hop.js build 

cd test/hopjs

run

./TEST

in order to run the hopjs test suite.

Documentation

An html documentation can be generated from source markdown files using hop.js:

cd doc && make && sudo make install

The main documentation file is <share-dir>/doc/hop/index.html where <share-dir> defaults to /usr/local/share.

Set startup preferences and run hop

Make sure that your $PATH variable includes the bin install directory (which defaults to /usr/local/bin).

By default Hop.js only accepts to serve authenticated requests. Before executing any programs users must be declared. These declarations go into the $HOME/.config/hop/hoprc.js file. The following declare a user named hopjs whose password is inria and that is allowed to execute any Hop.js service, the declaration services: "", and download any file readable from the server process, the declaration directories: "":

mkdir -p $HOME/.config/hop && cat > $HOME/.config/hop/hoprc.js << EOF
hop = require( "hop" );
var user = require( hop.user );
var config = require( hop.config );

user.add( { name: "hopjs",
                password: user.encryptPassword( "hopjs", "inria" ),
                services: "*",
                directories: "*"
          } );
EOF

Then start hop by running:

hop

hop starts the builtin web server on the default 8080 port. You may define an alternative port by typing instead the command:

hop -p <port>

Open your browser to the builtin web server: http://localhost:8080/hop (or http://localhost:PORT/hop )

You may also enforce the use of a custom preferences files using the --hoprc option.

hop --rc-file myrcfile.js

Run examples 

cd <hop-build-dir>

then run

hop examples/examples/examples.js

and open a browser on http://localhost:8080/hop/examples to play with hop.js examples.

Edit source code

hop.js syntax is a superset of JavaScript.

Most source files can be edited with a JavaScript editor. Some editors may have trouble with the extended syntax : the service keyword, the ~{} and ${} blocks, the <> tags.

First, look at your editor preferences for a possible support of non standard extensions. Emacs is known to provide extensive support for custom extensions (an emacs js mode hook file is provided as part of the hop.js distribution).

If you are still in trouble, you may split your code between standard node.js files and hop.js files, turning off the electric mode on files that use hop.js extensions.

Troubleshoot installation issues

Most common issues:

<bigloo-source>/autoconf/runtest -v10 -- bgl-pkg-config "--libs" "openssl"

would run the autoconfiguration test for openssl in verbose mode. Tools like ldd (or otool -L on OSX) are useful to track libraries issues.