# Script-Languages-Container-Tool
## Overview
The Script-Languages-Container-Tool (exaslct) is the build tool for the script language container.
You can build, export and upload script-language container from so-called flavors
which are description how to build the script language container. You can find pre-defined flavors
in the [script-languages-release](https://github.com/exasol/script-languages-release) repository.
There we also described how you could customize these flavors to your needs.
## In a Nutshell
### Prerequisites
#### For installation
In order to install this tool, your system needs to provide
the following prerequisites:
* Software
* Linux
* [bash](https://www.gnu.org/software/bash/) >= 4.2
* MacOsX
* [bash](https://www.gnu.org/software/bash/) > 3.2
* [coreutils](https://www.gnu.org/software/coreutils/)
* sha512sum
* sed
* [curl](https://curl.se/)
* Python 3 (>=3.8)
* Pip
#### For running
In order to use this tool, your system needs to fulfill the following prerequisites:
* Software
* Linux
* [bash](https://www.gnu.org/software/bash/) >= 4.2
* [coreutils](https://www.gnu.org/software/coreutils/)
* readlink with -f option
* realpath
* dirname
* MacOsX (Please see limitations on [MacOsX](#macosx-limitations))
* [bash](https://www.gnu.org/software/bash/) >= 3.2
* [coreutils](https://www.gnu.org/software/coreutils/)
* greadlink with -f option
* realpath
* dirname
* [Docker](https://docs.docker.com/) >= 17.05
* with support for [multi-stage builds required](https://docs.docker.com/develop/develop-images/multistage-build/)
* host volume mounts need to be allowed
* System Setup
* We recommend at least 50 GB free disk space on the partition
where Docker stores its images, on linux Docker typically stores
the images at /var/lib/docker.
* For the partition where the output directory (default: ./.build_output)
is located we recommend additionally at least 10 GB free disk space.
Further, prerequisites might be necessary for specific tasks. These are listed under the corresponding section.
### Installation
You have two options to use this project:
- as a pure Python project
- using the _start scripts_ which pull the correct container image from Dockerhub and execute it within the Docker container
#### Pure Python
Find the wheel package for a specific [release](https://github.com/exasol/script-languages-container-tool/releases) under assets.
Install the python package with `python3 -m pip install https://github.com/exasol/script-languages-container-tool/releases/download/$VERSION/exasol_script_languages_container_tool-$VERSION-py3-none-any.whl`. Replace $VERSION with the latest version or the specific version you are interested in.
#### Starter scripts
You need to install the Python package only once to install the starter scripts (see the [previous section](#installation)).
Install the starter scripts which allow to run exaslct within a docker image:
`python3 -m exasol_script_languages_container_tool.main install-starter-scripts --install-path $YOUR_INSTALL_PATH`
This will create a subfolder with the scripts itself and a symlink `exaslct` in $YOUR_INSTALL_PATH, which can be used as entry point.
### Usage
For simplicity the following examples use the starter script version (`exaslct`). If you want to use the pure Python package, simply replace `exaslct` with `python3 -m exasol_script_languages_container_tool.main` in all examples.
#### How to build an existing flavor?
Create the language container and export it to the local file system
```bash
./exaslct export --flavor-path=flavors/<flavor-name> --export-path <export-path>
```
or upload it directly into the BucketFS (currently http only, https follows soon)
```bash
./exaslct upload --flavor-path=flavors/<flavor-name> --database-host <hostname-or-ip> --bucketfs-port <port> \
--bucketfs-username w --bucketfs-password <password> --bucketfs-name <bucketfs-name> \
--bucket-name <bucket-name> --path-in-bucket <path/in/bucket>
```
Once it is successfully uploaded, it will print the ALTER SESSION statement
that can be used to activate the script language container in the database.
#### How to activate a script language container in the database
If you uploaded a container manually, you can generate the language activation statement with
```bash
./exaslct generate-language-activation --flavor-path=flavors/<flavor-name> --bucketfs-name <bucketfs-name> \
--bucket-name <bucket-name> --path-in-bucket <path/in/bucket> --container-name <container-name>
```
where \<container-name> is the name of the uploaded archive without its file extension. To activate the language, execute the generated statement in your database session to activate the container for the current session or system wide.
This command will print a SQL statement to activate the language similar to the following one:
```bash
ALTER SESSION SET SCRIPT_LANGUAGES='<LANGUAGE_ALIAS>=localzmq+protobuf:///<bucketfs-name>/<bucket-name>/<path-in-bucket>/<container-name>?lang=<language>#buckets/<bucketfs-name>/<bucket-name>/<path-in-bucket>/<container-name>/exaudf/exaudfclient[_py3]';
```
**Please, refer to the [User Guide](doc/user_guide/user_guide.md) for more detailed information, how to use exalsct.**
## Features
* Build a script language container as docker images
* Export a script language container as an archive which can be used for extending Exasol UDFs
* Upload a script language container as an archive to the Exasol DB's BucketFS
* Generating the activation command for a script language container
* Can use Docker registries, such as Docker Hub, as a cache to avoid rebuilding image without changes
* Can push Docker images to Docker registries
* Run tests for you container against an Exasol DB (docker-db or external db)
## Limitations
* Caution with symbolic links:
If you use symbolic links inside any directory of the command line arguments
they must not point to files or directories outside the root of the path of the
command line argument (i.e. --flavor-path ./flavors/my_flavor/ => There must be no symbolic
link inside ./flavors/my_flavor point to anywhere outside of ./flavors/my_flavor).
Background: Local directories paths must be mounted manually to the docker container.
We currently support only the mounting of the given command line arguments, but we do not analyze
the content of those directories.
Plan is to fix this limitation with [#35](https://github.com/exasol/script-languages-container-tool/issues/35)
### MacOsX Limitations
* On MacOsX all arguments (flavors path, output directory, etc.) must point to locations within the current directory (background is that the MacOsX version does not support mount binding additional directories).
## Table of Contents
### Information for Users
* [User Guide](doc/user_guide/user_guide.md)
* [Changelog](doc/changes/changelog.md)
## Information for Developers
* [Developer Guide](doc/developer_guide/developer_guide.md)
* [Dependencies](doc/dependencies.md)
Raw data
{
"_id": null,
"home_page": "https://github.com/exasol/script-languages-container-tool",
"name": "exasol-script-languages-container-tool",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4",
"maintainer_email": "",
"keywords": "exasol,udf,script-languages",
"author": "Torsten Kilias",
"author_email": "torsten.kilias@exasol.com",
"download_url": "https://files.pythonhosted.org/packages/0d/94/a0e0cab50f026e4847a6c1c7367fbbdd5e05774bac34fa1ad2080f76d377/exasol_script_languages_container_tool-0.18.2.tar.gz",
"platform": null,
"description": "# Script-Languages-Container-Tool\n\n## Overview\n\nThe Script-Languages-Container-Tool (exaslct) is the build tool for the script language container.\nYou can build, export and upload script-language container from so-called flavors \nwhich are description how to build the script language container. You can find pre-defined flavors \nin the [script-languages-release](https://github.com/exasol/script-languages-release) repository. \nThere we also described how you could customize these flavors to your needs.\n\n## In a Nutshell\n\n### Prerequisites\n\n#### For installation\n\nIn order to install this tool, your system needs to provide \nthe following prerequisites:\n\n* Software\n * Linux\n * [bash](https://www.gnu.org/software/bash/) >= 4.2\n * MacOsX\n * [bash](https://www.gnu.org/software/bash/) > 3.2\n * [coreutils](https://www.gnu.org/software/coreutils/)\n * sha512sum\n * sed\n * [curl](https://curl.se/)\n * Python 3 (>=3.8)\n * Pip\n\n\n#### For running\n\nIn order to use this tool, your system needs to fulfill the following prerequisites:\n\n* Software\n * Linux\n * [bash](https://www.gnu.org/software/bash/) >= 4.2\n * [coreutils](https://www.gnu.org/software/coreutils/)\n * readlink with -f option\n * realpath \n * dirname\n * MacOsX (Please see limitations on [MacOsX](#macosx-limitations))\n * [bash](https://www.gnu.org/software/bash/) >= 3.2\n * [coreutils](https://www.gnu.org/software/coreutils/)\n * greadlink with -f option\n * realpath \n * dirname\n * [Docker](https://docs.docker.com/) >= 17.05 \n * with support for [multi-stage builds required](https://docs.docker.com/develop/develop-images/multistage-build/)\n * host volume mounts need to be allowed\n\n* System Setup \n * We recommend at least 50 GB free disk space on the partition \n where Docker stores its images, on linux Docker typically stores \n the images at /var/lib/docker.\n * For the partition where the output directory (default: ./.build_output)\n is located we recommend additionally at least 10 GB free disk space.\n\nFurther, prerequisites might be necessary for specific tasks. These are listed under the corresponding section.\n\n### Installation\n\nYou have two options to use this project:\n - as a pure Python project\n - using the _start scripts_ which pull the correct container image from Dockerhub and execute it within the Docker container\n\n#### Pure Python\n\nFind the wheel package for a specific [release](https://github.com/exasol/script-languages-container-tool/releases) under assets.\n\nInstall the python package with `python3 -m pip install https://github.com/exasol/script-languages-container-tool/releases/download/$VERSION/exasol_script_languages_container_tool-$VERSION-py3-none-any.whl`. Replace $VERSION with the latest version or the specific version you are interested in.\n\n#### Starter scripts\n\nYou need to install the Python package only once to install the starter scripts (see the [previous section](#installation)).\n\nInstall the starter scripts which allow to run exaslct within a docker image:\n`python3 -m exasol_script_languages_container_tool.main install-starter-scripts --install-path $YOUR_INSTALL_PATH`\n\nThis will create a subfolder with the scripts itself and a symlink `exaslct` in $YOUR_INSTALL_PATH, which can be used as entry point.\n\n### Usage\n\nFor simplicity the following examples use the starter script version (`exaslct`). If you want to use the pure Python package, simply replace `exaslct` with `python3 -m exasol_script_languages_container_tool.main` in all examples. \n\n#### How to build an existing flavor?\n\nCreate the language container and export it to the local file system\n\n```bash\n./exaslct export --flavor-path=flavors/<flavor-name> --export-path <export-path>\n```\n\nor upload it directly into the BucketFS (currently http only, https follows soon)\n\n```bash\n./exaslct upload --flavor-path=flavors/<flavor-name> --database-host <hostname-or-ip> --bucketfs-port <port> \\ \n --bucketfs-username w --bucketfs-password <password> --bucketfs-name <bucketfs-name> \\\n --bucket-name <bucket-name> --path-in-bucket <path/in/bucket>\n```\n\nOnce it is successfully uploaded, it will print the ALTER SESSION statement\nthat can be used to activate the script language container in the database.\n\n#### How to activate a script language container in the database\n\nIf you uploaded a container manually, you can generate the language activation statement with\n\n```bash\n./exaslct generate-language-activation --flavor-path=flavors/<flavor-name> --bucketfs-name <bucketfs-name> \\\n --bucket-name <bucket-name> --path-in-bucket <path/in/bucket> --container-name <container-name>\n```\n\nwhere \\<container-name> is the name of the uploaded archive without its file extension. To activate the language, execute the generated statement in your database session to activate the container for the current session or system wide.\n\nThis command will print a SQL statement to activate the language similar to the following one:\n\n```bash\nALTER SESSION SET SCRIPT_LANGUAGES='<LANGUAGE_ALIAS>=localzmq+protobuf:///<bucketfs-name>/<bucket-name>/<path-in-bucket>/<container-name>?lang=<language>#buckets/<bucketfs-name>/<bucket-name>/<path-in-bucket>/<container-name>/exaudf/exaudfclient[_py3]';\n```\n\n**Please, refer to the [User Guide](doc/user_guide/user_guide.md) for more detailed information, how to use exalsct.**\n\n## Features\n\n* Build a script language container as docker images\n* Export a script language container as an archive which can be used for extending Exasol UDFs\n* Upload a script language container as an archive to the Exasol DB's BucketFS\n* Generating the activation command for a script language container\n* Can use Docker registries, such as Docker Hub, as a cache to avoid rebuilding image without changes\n* Can push Docker images to Docker registries\n* Run tests for you container against an Exasol DB (docker-db or external db)\n\n## Limitations\n\n* Caution with symbolic links: \n If you use symbolic links inside any directory of the command line arguments\n they must not point to files or directories outside the root of the path of the \n command line argument (i.e. --flavor-path ./flavors/my_flavor/ => There must be no symbolic\n link inside ./flavors/my_flavor point to anywhere outside of ./flavors/my_flavor).\n Background: Local directories paths must be mounted manually to the docker container. \n We currently support only the mounting of the given command line arguments, but we do not analyze\n the content of those directories.\n Plan is to fix this limitation with [#35](https://github.com/exasol/script-languages-container-tool/issues/35)\n\n\n### MacOsX Limitations\n \n* On MacOsX all arguments (flavors path, output directory, etc.) must point to locations within the current directory (background is that the MacOsX version does not support mount binding additional directories).\n\n## Table of Contents\n\n### Information for Users\n\n* [User Guide](doc/user_guide/user_guide.md)\n* [Changelog](doc/changes/changelog.md)\n\n## Information for Developers\n\n* [Developer Guide](doc/developer_guide/developer_guide.md)\n* [Dependencies](doc/dependencies.md)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Script Languages Container Tool",
"version": "0.18.2",
"project_urls": {
"Homepage": "https://github.com/exasol/script-languages-container-tool",
"Repository": "https://github.com/exasol/script-languages-container-tool"
},
"split_keywords": [
"exasol",
"udf",
"script-languages"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "118e255c9bf41b54833ce08b92ca109a5740ed6e9ab20e9a0dc9ce8d67cdaa95",
"md5": "79ef2bcec49900470fd58212d8c14c29",
"sha256": "15f8f353bd04e115d78e9c152a8c916b36e5de530c32baefe4fd7182645be36d"
},
"downloads": -1,
"filename": "exasol_script_languages_container_tool-0.18.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "79ef2bcec49900470fd58212d8c14c29",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4",
"size": 86433,
"upload_time": "2024-02-19T18:28:20",
"upload_time_iso_8601": "2024-02-19T18:28:20.116137Z",
"url": "https://files.pythonhosted.org/packages/11/8e/255c9bf41b54833ce08b92ca109a5740ed6e9ab20e9a0dc9ce8d67cdaa95/exasol_script_languages_container_tool-0.18.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0d94a0e0cab50f026e4847a6c1c7367fbbdd5e05774bac34fa1ad2080f76d377",
"md5": "34b59ab80dafd11773892395e3b1035c",
"sha256": "7bea396390aa1fb3b640c4b22cb046356cdc523f15eb372c2f33307610305d49"
},
"downloads": -1,
"filename": "exasol_script_languages_container_tool-0.18.2.tar.gz",
"has_sig": false,
"md5_digest": "34b59ab80dafd11773892395e3b1035c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4",
"size": 42553,
"upload_time": "2024-02-19T18:28:21",
"upload_time_iso_8601": "2024-02-19T18:28:21.545085Z",
"url": "https://files.pythonhosted.org/packages/0d/94/a0e0cab50f026e4847a6c1c7367fbbdd5e05774bac34fa1ad2080f76d377/exasol_script_languages_container_tool-0.18.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-19 18:28:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "exasol",
"github_project": "script-languages-container-tool",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "exasol-script-languages-container-tool"
}
JSON
