.. _customization_intro: Process overview ###################### To customize your oSL Web App, follow these steps in the order they are presented. .. _unpack_the_solution: Unpack the solution =================== The solution file, which has an ``.awa`` extension, is in a compressed format and contains all the necessary files for the solution. In order to customize the solution, you first need to unpack it by following these steps: .. vale Google.Ellipses = NO #. Rename the file to ``.zip``. a. In the file explorer, right-click the solution file and select **Rename**. b. Change the file extension from ``.awa`` to ``.zip``. #. Unzip the solution file. In the file explorer, right-click the file, select **Extract All** (Windows) or **Extract to...** (Linux) and follow the instructions. Alternatively, you can use any other zip utility --- such as 7-Zip or WinRAR on Windows, or the ``gunzip`` command on Linux --- to extract the files. .. vale Google.Ellipses = YES The solution files are extracted to a folder with the same name as the solution file and which contains files similar to the following: .. code-block:: text │ ├── assets │ ├── saf_inner_source_packages.tar.gz │ └── saf_inner_source_packages_ui.tar.gz ├── doc │ ├── source │ ├── styles │ ├── Makefile │ └── make.bat ├── examples │ └── README.md ├── src │ └── ansys ├── telemetry │ ├── grafana │ └── tracelens ├── tests │ ├── common_test_files │ ├── integration │ ├── unit │ └── conftest.py ├── .gitignore ├── .pre-commit-config.yaml ├── CHANGELOG.md ├── CODEOWNERS ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── README.rst ├── poetry.lock ├── poetry.toml ├── pyproject.toml ├── setup_environment.py └── tox.ini Customize the solution ======================= Follow these instructions to modify your solution. Based on the complexity of the code modifications required, the instructions have been grouped into "no-code," "low-code," and "full-code" customizations: .. list-table:: :stub-columns: 1 * - No-code customizations - Do not require modifications to the source code, only to asset files (for example, image or text files). * - Low-code customizations - Require some code modifications, but usually involve a utility function created for this use case. * - Full-code customizations - Require you to write your own Python code. Here is an example of what you can do with the no-code and low-code customizations that are described in this user guide. Consider the default look of the application, with no modifications: .. image:: ../img/setup_results_default.png Compare that with the look of the app if you follow the no-code/low-code instructions across all sections of this customization guide, using the assets from the examples: .. image:: ../img/setup_results_custom.png Version the changes =================== The solution folder contains a ``pyproject.toml`` file which details the solution metadata and lists the dependencies required to build and execute the solution. To keep track of the customization changes made to the solution, it is recommended that you version the changes by incrementing the ``version`` property in the ``pyproject.toml`` file. The ``version`` property is located in the ``[tool.poetry]`` section of the file. .. vale off .. code-block:: toml :emphasize-lines: 15 [build-system] requires = ["poetry-core>=1.0.0,<1.3.0", "setuptools>=65.0"] build-backend = "poetry.core.masonry.api" # The following lines were added to enforce the poetry version needed for the project. # It will be read by the setup_environment.py script to install this version. [build-system-requirements] build-system-version = "1.7.0" [tool.saf-osl-app-builder] version = "0.4.0" [tool.poetry] name = "ansys-solutions-tuning-fork" version = "0.1.dev0" description = "An optiSLang (web) application" license = "Proprietary" authors = ["ANSYS, Inc. "] maintainers = ["ANSYS, Inc. "] readme = "README.rst" keywords = ["Ansys Solutions"] .. vale on If your solution is being deployed in a containerized environment, updating the ``version`` property allows different versions of the same solution to be deployed. For example, if ``.awa`` files with the *same* solution name but *different* versions are uploaded, the Ansys App Portal displays them as separate apps. .. note:: You should not modify the solution dependencies, as it may break compatibility with the environment where the solution is executed. .. _test_the_changes: Test the changes ================= To test and debug your customization changes, you need to set up the development environment. To do this, follow these instructions: #. Move to the solution directory: .. code-block:: bash cd #. Install ``toml`` and ``packaging`` on your current system Python interpreter: .. code-block:: bash pip install toml packaging #. Install the Python ecosystem: .. tabs:: .. code-tab:: bat :caption: CMD/PowerShell python setup_environment.py -d desktop run ui .. code-tab:: bash :caption: Bash python3 setup_environment.py -d desktop run ui .. note:: To use a version other than the latest, use the ``-n`` flag followed by the desired version. For example, to use Ansys 2025 R1, use ``-n 251``. A virtual environment named ``.venv`` is now available in the solution. #. Activate the virtual environment: .. tabs:: .. code-tab:: bat :caption: CMD .venv\Scripts\activate.bat .. code-tab:: powershell :caption: PowerShell .venv\Scripts\Activate.ps1 .. code-tab:: bash :caption: Bash source .venv/bin/activate .. tip:: You may be interested in using the additional ``-d style`` value to install the code styling dependencies when you install the Python ecosystem: .. tabs:: .. code-tab:: bat :caption: CMD/PowerShell python setup_environment.py -d desktop run ui style .. code-tab:: bash :caption: Bash python3 setup_environment.py -d desktop run ui style This allows you to run a number of code style checkers with the pre-commit tool to ensure that the code is formatted correctly: .. code-block:: bash pre-commit run --all-files --show-diff-on-failure After activating the environment, you can run the solution by executing the following command from the root of the solution directory: .. code:: powershell run_solution .. attention:: If your Ansys software suite version is earlier than 25R2, ``run_solution`` is not available. Instead, use this command: .. tabs:: .. code-tab:: bat :caption: CMD python "\\optiSLang\lib\python3.10\Lib\saf_executables\solution-app-starter.exe" . .. code-tab:: powershell :caption: PowerShell python "\\optiSLang\lib\python3.10\Lib\saf_executables\solution-app-starter.exe" . .. code-tab:: bash :caption: Bash python3 "//optiSLang/lib/python3.10/lib/python3.10/saf_executables/solution-app-starter" . Be sure to replace ```` and ```` with the correct paths. Repackage the solution ======================== Once you are done with the customization changes, you need to repackage the solution into an ``.awa`` file. The updated solution can be executed as usual, allowing you to check the changes are as expected. To pack the solution back into an ``.awa`` file, use the following steps in the file explorer: .. vale Google.Ellipses = NO #. Select all the files and folders in the solution folder. #. Right-click the selected files and select :menuselection:`Send to --> Compressed (zipped) folder` (Windows) or :menuselection:`Compress...` (Linux). #. Rename the new ``.zip`` file to ``.awa``. .. vale Google.Ellipses = YES Alternatively, you can use any other zip utility like 7-Zip or WinRAR on Windows, or gzip on Linux to compress the files. .. attention:: While having extra content does not break the ``.awa`` file, the ``.poetry``, ``.venv``, ``.ruff_cache`` and/or ``.pytest_cache`` folders (depending on what the development environment generated) are only necessary for development purposes and may considerably bloat the size of the ``.awa`` file. It is strongly recommended that you exclude them from repackaging e. g. by deleting them before compression. The ``poetry.toml`` file is also similarly unnecessary. Execute the customized solution ================================= To execute the new ``.awa`` file: Windows -------- Double-click the ``.awa`` file in the file explorer. This opens the solution in a new window. Linux ------- Use the following command: .. tabs:: .. code-tab:: bash :caption: Bash //optiSLang/tools/saf/run_solution .awa and open the URL printed in the console in a web browser.