From 8631a84f37b22b0ef50d809bce6ac7406dca5907 Mon Sep 17 00:00:00 2001 From: Fabien Lelaquais Date: Thu, 4 Jan 2024 19:10:54 +0100 Subject: [PATCH] Add instructions to build Taipy's and Taipy's GUI JavaScript bundles. --- INSTALLATION.md | 135 +++++++++++++++++++++++++++++++++++ frontend/README.md | 14 ++++ frontend/taipy-gui/README.md | 34 +++++++++ frontend/taipy/README.md | 27 +++++++ 4 files changed, 210 insertions(+) create mode 100644 INSTALLATION.md create mode 100644 frontend/README.md create mode 100644 frontend/taipy-gui/README.md create mode 100644 frontend/taipy/README.md diff --git a/INSTALLATION.md b/INSTALLATION.md new file mode 100644 index 0000000000..2607c3a29b --- /dev/null +++ b/INSTALLATION.md @@ -0,0 +1,135 @@ +# Installation + +There are different ways to install Taipy, depending on how you plan to use it. + +If your goal is to look into the code, modify and improve it, go straight +to the [source installation](#installing-for-development) section. + +Taipy needs your system to have Python 3.8 or above installed. + +## Installing from PyPI + +The easiest way to install Taipy is from the +[Pypi software repository](https://pypi.org/project/taipy/). + +Run the command: +```console +$ pip install taipy +``` + +If you are running in a virtual environment, you will have to issue the command: +```console +$ pipenv install taipy +``` + +These commands install the `taipy` package in the Python environment with all its +dependencies. + +## Installing from GitHub + +The development version of Taipy is updated daily with changes from the Taipy R&D and external +contributors whom we praise for their input. + +The development version of Taipy can be installed using *pip* and *git*: + +```console +$ pip install git+https://git@github.com/Avaiga/taipy +``` + +## Installing for development + +If you need the source code for Taipy on your system so you can see how things are done or maybe +participate in the improvement of the packages, you can clone the GitHub repository: + +```console +$ git clone https://github.com/Avaiga/taipy.git +``` + +This creates the 'taipy' directory holding all the package's source code. + +### Building the JavaScript bundles + +Taipy (and Taipy GUI that it embeds) has some code dealing with the client side of the web +applications.
+This code is written in [TypeScript](https://www.typescriptlang.org/), relies on +[React](https://reactjs.org/) components, and is packaged into JavaScript bundles that are sent to +browsers when they connect to all Taipy applications that have a graphical interface. + +There are two main JavaScript bundles that can be built: +- Taipy GUI: All the graphical interfaces that Taipy GUI can generate are based on a set of + generated files, including the web application and all the predefined visual elements. +- Taipy: A set of visual elements dedicated to Scenario Management. + +**Prerequisites**: If you need to build the JavaScript bundle, you need to make sure that the +[Node.js](https://nodejs.org/) JavaScript runtime version 18 or above is installed on your +machine.
+Note that Node.js comes with the [`npm` package manager](https://www.npmjs.com/) as part +of the standard installation. + +The build process is described in the [Taipy GUI front-end](frontend/taipy-gui/README.md) and + [Taipy front-end](frontend/taipy/README.md) README files.
+ The Taipy GUI bundle must be built first, as the Taipy front-end code depends on it. + +Here is the sequence of commands that can be issued to build both sets of files: + +```console +# Current directory is the repository's root directory +# +# Build the Taipy GUI bundle +$ cd frontend/taipy-gui +$ cd dom +$ npm i +$ cd .. +$ npm i --omit=optional +$ npm run build +# +# Build the Taipy front-end bundle +$ cd ../taipy # Current directory is [taipy-dir]/frontend/taipy +$ npm i +$ npm run build +``` + +These commands should create the directories `taipy/gui/webapp` and `taipy/gui_core/lib` in the +root directory of the taipy repository. + +### Debugging the JavaScript bundles + +If you plan to modify the front-end code and need to debug the TypeScript +code, you must use the following: +``` +$ npm run build:dev +``` + +instead of the *standard* build option. + +This will preserve the debugging symbols, and you will be able to navigate in the +TypeScript code from your debugger. + +> **Note:** Web application location +> +> When you are developing front-end code for the Taipy GUI package, it may +> be cumbersome to have to install the package over and over when you know +> that all that has changed is the JavaScript bundle that makes the Taipy +> web app. +> +> By default, the Taipy GUI application searches for the front-end code +> in the `[taipy-gui-package-dir]/taipy/gui/webapp` directory.
+> You can, however, set the environment variable `TAIPY_GUI_WEBAPP_PATH` +> to the location of your choice, and Taipy GUI will look for the web +> app in that directory.
+> If you set this variable to the location where you build the web app +> repeatedly, you will no longer have to reinstall Taipy GUI before you +> try your code again. + + +## Running the tests + +To run the tests on the package, you need to create a virtual +environment and install the development packages: + +Here are the commands to issue: + +```console +pipenv install --dev +pipenv run pytest +``` diff --git a/frontend/README.md b/frontend/README.md new file mode 100644 index 0000000000..0d78d754af --- /dev/null +++ b/frontend/README.md @@ -0,0 +1,14 @@ +# Front-end source code + +This directory contains the source code for the front-end parts of Taipy GUI and Taipy. + +- `./taipy-gui`: The source files for building the front-end part of Taipy GUI.
+ This includes the web application used by Taipy GUI to expose user interfaces as + well as all the visual elements, implemented in React. +- `./taipy`: The source files for building the front-end part of Taipy.
+ This includes all the Taipy elements for Scenario Management. + +Note that before the `taipy` part is built, the `taipy-gui` part must have been built. + +Please check the [Taipy GUI Front-end](taipy-gui/README.md) and [Taipy Front-end](taipyREADME.md) +README files for details. diff --git a/frontend/taipy-gui/README.md b/frontend/taipy-gui/README.md new file mode 100644 index 0000000000..c5de498e79 --- /dev/null +++ b/frontend/taipy-gui/README.md @@ -0,0 +1,34 @@ +# Taipy GUI front-end + +This directory contains the source code of the Taipy GUI front-end bundle that includes the +web app and all the elements natively available in Taipy GUI. + +## Prerequisites + +[Node.js](https://nodejs.org/) JavaScript runtime version 18 or above must be installed on your +machine.
+Note that Node.js comes with the [`npm` package manager](https://www.npmjs.com/) as part +of the standard installation. + +## Build + +To build the Taipy GUI bundle, you must set your current directory to this directory and then +run the following commands: + +```console +# Current directory is the directory where this README file is located: +# [taipy-dir]/frontend/taipy-gui +# +# Install the DOM dependencies (once and for all) +$ cd dom +$ npm i +$ cd .. +# Install the web app dependencies +$ npm i --omit=optional +# Build the web app and all elements +$ npm run build +``` + + +After these commands are successfully executed, a new directory will be created in +`[taipy-dir]/taipy/gui/webapp` containing all the code that the Taipy GUI front-end relies on. diff --git a/frontend/taipy/README.md b/frontend/taipy/README.md new file mode 100644 index 0000000000..4cd375b99c --- /dev/null +++ b/frontend/taipy/README.md @@ -0,0 +1,27 @@ +# Taipy front-end + +This directory contains the source code of the Taipy front-end bundle that includes the +Scenario Management elements. + +## Prerequisites + +The Taipy GUI front-end web application must have been built.
+Check [this file](../taipy-gui/README.md) for more information. + +## Build + +To build the Taipy bundle, you must set your current directory to this directory and then +run the following commands: + +```console +# Current directory is the directory where this README file is located: +# [taipy-dir]/frontend/taipy +# +$ npm i +# Build the Taipy front-end bundle +$ npm run build +``` + +After these commands are successfully executed, a new directory will be created in +`[taipy-dir]/taipy/gui_core/lib` containing all the code that implements the Taipy visual elements +for Scenario Management.