#-------------------------------------------------------------------------
# File: Anaconda3User-ReadMeFirst.txt
#                              in macbuild/Resources/script-bundle-A.zip
#
# Last modified: 2025-11-09
#-------------------------------------------------------------------------

This folder contains the "KLayoutAna3.app" script bundle and some sample icon files.


[1] Anaconda3 setup
    First, you must set up the Anaconda3 environment to use this package.
    Through this document, we use "Anaconda3-2025.06-0-MacOSX-[arm64|x86_64].pkg".
    The installation root directory is:
      arm64:  /opt/anaconda3
      x86_64: /Applications/anaconda3/
              If installed under $HOME/opt/anaconda3/, make a symbolic link:
                 /Applications/andconda3 ---> $HOME/opt/anaconda3/

    I found that Qt 6.x is required to use the package.
    We use a virtual environment to make Python package management easier.

    [arm64]
      Qt6 is to be installed under /opt/anaconda3/envs/klayout-qt6
      after installing "Anaconda3-2025.06-0-MacOSX-arm64.pkg" under /opt/anaconda3/.

      1) Create a new env "klayout-qt6" (with stable solver & channels)
         switch solver to libmamba for faster/more stable resolves
           $ conda install -n base -y conda-libmamba-solver
           $ conda config --set solver libmamba

         Create the environment (on this ARM machine it will pull osx-arm64 builds)
           $ conda create -n klayout-qt6 python=3.13 -y
           $ conda activate klayout-qt6

         In this env only, prefer conda-forge strictly (to avoid mixing)
           $ conda config --env --add channels conda-forge
           $ conda config --env --add channels defaults
           $ conda config --env --set channel_priority strict
           $ conda install -n base -y conda-libmamba-solver
           $ conda config --set solver libmamba

      2) Install Qt6 (qt6-main and qt6-multimedia) only from conda-forge
         Qt6 core (builds that typically include Designer/UiTools)
           $ conda install -y --override-channels -c conda-forge "qt6-main=6.9.3"
           $ conda install -y --override-channels -c conda-forge "qt6-multimedia=6.9.3"

      3) Additionally, install Ruby and libgit2 only from conda-forge
           $ conda install -y --override-channels -c conda-forge "ruby=3.4.7"
           $ conda install -y --override-channels -c conda-forge "libgit2=1.9.1"

    [x86_64]
      Qt6 is to be installed under /Applications/anaconda3/envs/klayout-qt6
      after installing "Anaconda3-2025.06-0-MacOSX-x86_64.pkg" under /Applications/anaconda3/.

      1) Create a new env "klayout-qt6" (with stable solver & channels)
         switch solver to libmamba for faster/more stable resolves
           $ conda install -n base -y conda-libmamba-solver
           $ conda config --set solver libmamba

         Create the environment (on this x86_64 machine it will pull osx-64 builds)
           $ conda create -n klayout-qt6 python=3.13 -y
           $ conda activate klayout-qt6

         In this env only, prefer conda-forge strictly (to avoid mixing)
           $ conda config --env --add channels conda-forge
           $ conda config --env --add channels defaults
           $ conda config --env --set channel_priority strict
           $ conda install -n base -y conda-libmamba-solver
           $ conda config --set solver libmamba

      2) Install Qt6 (qt6-main and qt6-multimedia) only from conda-forge
         Qt6 core (builds that typically include Designer/UiTools)
           $ conda install -y --override-channels -c conda-forge "qt6-main=6.9.3"
           $ conda install -y --override-channels -c conda-forge "qt6-multimedia=6.9.3"

      3) Additionally, install Ruby and libgit2 only from conda-forge
           $ conda install -y --override-channels -c conda-forge "ruby=3.4.7"
           $ conda install -y --override-channels -c conda-forge "libgit2=1.9.1"

[2] KLayoutAna3.app
    This bundle is for those with the Anaconda3 environment under /opt/anaconda3 or /Applications/anaconda3.
    The CPU architecture is automatically detected, and the virtual environment is also set automatically.
    Drag and drop this launcher bundle to the /Applications directory.
    As the bundle consists of a simple Bash script, you may be able to edit it as you like
    with the help of the "Automator.app" tool.

    KLayout's configuration file is "$HOME/.klayout/klayoutrc."
    You can invoke multiple instances of KLayout using this script bundle.


[3] KLayoutAna3.app.Bash
    This file is the source Bash script of the "KLayoutAna3.app" bundle.
    You can refer to this script and use the "Automator.app" tool to create your script bundle
    from scratch. See the "KLayoutAna3.app.png" image file.


[4] Application Icons
    You can change the application icon of a script bundle using "Finder."
      1) Right-click the launcher bundle "*.app" and "Get info."
      2) Click the default "robot icon" at the top-left, highlighting it.
      3) Drag and drop any icon onto the "robot icon."


[5] Klayout Standalone Python Package
    This LW*.dmg may contain the KLayout standalone Python package (klayout*.whl) compliant with the base Python system.
    Refer to "pymod-pip3-ana3.txt" for more details.
    You can either install the latest package from the official PyPI website at any time:
      https://pypi.org/project/klayout/.


[6] Using the git-based Salt Package Manager through a proxy server
    If you use the git-based Salt Package Manager through a proxy server, you need to set
    the 'KLAYOUT_GIT_HTTP_PROXY' environment variable. For example,
    ```
      $ export KLAYOUT_GIT_HTTP_PROXY="http://111.222.333.444:5678"
    ```
    Ask your system administrator for the actual IP address and port number of your proxy server.

    Downloading data from the package server might time out (default is 10 sec).
    If so, set the 'KLAYOUT_HTTP_TIMEOUT' environment variable.
    For example, to make a timeout of 20 seconds,
    ```
      $ export KLAYOUT_HTTP_TIMEOUT=20
    ```

[EOF]
