#-------------------------------------------------------------------------
# File: Homebrew-HUser-ReadMeFirst.txt
#                              in macbuild/Resources/script-bundle-H.zip
#
# "-H" implies "Heavy weight", "Hybrid", and "Heterogeneous".
#
# Last modified: 2024-09-23
#-------------------------------------------------------------------------

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

[1] MacPorts and Homebrew setup
    Unlike the sibling DMGs like "LW-klayout-0.29.6-macOS-Sonoma-1-qt6Brew-Rhb33Phb312.dmg,"
    this package contains the Qt5 from MacPorts and Python 3.11.x frameworks from Homebrew.
    Therefore, you don't need to install the MacPorts and Homebrew development environments.
    The Ruby framework is the OS-bundled one. Hence, this is a "hybrid" system.

    You can use the built-in 'pip' tool to install different Python packages as below.
    Here, let's install 'pandas', 'scipy', and 'matplotlib', for example.
      1) Start the Terminal

      2) $ cd /Applications/klayout.app/Contents/MacOS

      3) $ ./start-console.py   <=== this will invoke the built-in Python
        Python 3.11.10 (main, Sep  7 2024, 01:03:31)  \  <=== Python version may differ
        [Clang 15.0.0 (clang-1500.3.9.4)] on darwin
        Type "help", "copyright", "credits" or "license" for more information.
        (KLayout Python Console)

        >>> howtopip()

        --------------------------------------------------------------------------------
        (1) Install ['pandas', 'scipy', 'matplotlib']
        >>> import pip
        >>> pip.main( ['install', 'pandas', 'scipy', 'matplotlib'] + piptarget )

        (2) List modules
        >>> import pip
        >>> pip.main( ['list'] )

        (3) Uninstall ['scipy']
        >>> import pip
        >>> pip.main( ['uninstall', 'scipy'] )
        --------------------------------------------------------------------------------

        >>> import pip

        >>> pip.main( ['install', 'pandas', 'scipy', 'matplotlib'] + piptarget )

        WARNING: pip is being invoked by an old script wrapper. This will fail in a future version of pip.
        Please see https://github.com/pypa/pip/issues/5599 for advice on fixing the underlying issue.
        To avoid this problem you can invoke Python with '-m pip' instead of running pip directly.
        Collecting pandas
          Using cached pandas-2.2.3-cp311-cp311-macosx_10_9_x86_64.whl.metadata (89 kB)
        Collecting scipy
          Using cached scipy-1.14.1-cp311-cp311-macosx_14_0_x86_64.whl.metadata (60 kB)
        Collecting matplotlib
          Using cached matplotlib-3.9.2-cp311-cp311-macosx_10_12_x86_64.whl.metadata (11 kB)
        Collecting numpy>=1.23.2 (from pandas)
          Using cached numpy-2.1.1-cp311-cp311-macosx_14_0_x86_64.whl.metadata (60 kB)
        :
        :
        Successfully installed contourpy-1.3.0 cycler-0.12.1 fonttools-4.53.1 kiwisolver-1.4.7 \
                     matplotlib-3.9.2 numpy-2.1.1 packaging-24.1 pandas-2.2.3 pillow-10.4.0
                     pyparsing-3.1.4 python-dateutil-2.9.0.post0 pytz-2024.2 scipy-1.14.1 six-1.16.0 \
                     tzdata-2024.1
        0

        >>> quit()


[2] KLayoutHomebrew-H.app
    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-H.app.Bash
    This file is the source Bash script of the "KLayoutHomebrew-H.app" bundle.
    You can refer to this script and use the "Automator.app" tool to create your script bundle
    from scratch. See the "KLayoutHomebrew-H.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] 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]
