#-------------------------------------------------------------------------
# File: HomebrewUser-ReadMeFirst.txt
#                              in macbuild/Resources/script-bundle-B.zip
#
# Last modified: 2025-01-04
#-------------------------------------------------------------------------

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


[1] Homebrew setup
    First, you must set up the Homebrew environment to use this package.
    Install the **Intel Version Homebrew** to its default location (/usr/local for macOS Intel;
    cf. /opt/homebrew for Apple Silicon).
       Ref. https://github.com/Homebrew/brew/blob/master/docs/Installation.md#alternative-installs.

    If you are using an Apple Silicon machine, according to a piece of web information,
    specify the architecture name like:
        % arch -x86_64  /bin/bash -c \
           "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    At least you have to install Qt6 (version 6.7.x), Ruby (version 3.4.x),
    Python (version 3.12.x), and libgit2 (version 1.9.x) packages:
        $ brew install qt@6
        $ brew install ruby@3.4
        $ brew install python@3.12
        $ brew install libgit2

    The main reason you chose this package would be to use KLayout's PYA in Python 3.x.
    The attached file "HomebrewPythonPip.txt" has captured the steps I followed to add some
    Python modules using the "pip" command on Catalina.
    Please note that the module versions may not be up-to-date.

    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    <<< Important Notes for Homebrew python@3.12 >>>
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    This DMG is built with Homebrew python@3.12, where we cannot use the legacy "pip3" command.
    More precisely, we will get the following errors, if we attempt.
      $ python3 -m pip install pandas scipy matplotlib XlsxWriter openpyxl
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      error: externally-managed-environment

      × This environment is externally managed
      ╰─> To install Python packages system-wide, try brew install
          xyz, where xyz is the package you are trying to
          install.

          If you wish to install a Python library that isn't in Homebrew,
          use a virtual environment:

          python3 -m venv path/to/venv
          source path/to/venv/bin/activate
          python3 -m pip install xyz

          If you wish to install a Python application that isn't in Homebrew,
          it may be easiest to use 'pipx install xyz', which will manage a
          virtual environment for you. You can install pipx with

          brew install pipx

          You may restore the old behavior of pip by passing
          the '--break-system-packages' flag to pip, or by adding
          'break-system-packages = true' to your pip.conf file. The latter
          will permanently disable this error.

          If you disable this error, we STRONGLY recommend that you additionally
          pass the '--user' flag to pip, or set 'user = true' in your pip.conf
          file. Failure to do this can result in a broken Homebrew installation.

          Read more about this behavior here: <https://peps.python.org/pep-0668/>

      note: If you believe this is a mistake, please contact your Python installation or OS distribution provider.
      You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
      hint: See PEP 668 for the detailed specification.

    To avoid this error, use a virtual environment as suggested above. For example,
      $ python3 -m venv $HOME/opt/HBPy312
      $ source $HOME/opt/HBPy312/bin/activate
      $ python3 -m pip install install pandas scipy matplotlib XlsxWriter openpyxl

    Then, set the "KLAYOUT_PYTHONPATH" environment variable before starting "klayout.app".
    (Ref. https://www.klayout.de/forum/discussion/2557/)
      $ export VIRTUAL_ENV=$HOME/opt/HBPy312
      $ export KLAYOUT_PYTHONPATH=$VIRTUAL_ENV/lib/python3.12/site-packages

    The best approach is to create a script bundle (launching service), as described in [2] and [3].
    Refer to "KLayoutHomebrew.app.Bash" for details.


[2] KLayoutHomebrew.app
    This bundle is for those with the Homebrew environment under /usr/local/opt/ (for macOS Intel)
    or /opt/homebrew/opt/ (for Apple Silicon).
    Optionally, drag and drop this bundle to the /Applications directory, too.
    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.

    The built-in Bash script sets the LANG environment variable, then invokes
    "/Applications/klayout.app" in the EDITOR mode.

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


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


[4] Application Icons
    You can change the application icon of a script bundle using "Finder."
      1) Right-click script 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
    The LW*.dmg, only if built with python@3.11, contains the KLayout standalone Python package
    (klayout*.whl) compliant with the base Python system.
    Refer to "pymod-pip3-hb311.txt" for more details.
    You can either install the 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]
