#-------------------------------------------------------------------------
# File: Homebrew-HUser-ReadMeFirst.txt
#                              in macbuild/Resources/script-bundle-H.zip
#
# "-H" implies "Heavy weight" and "Hybrid"
#
# Last modified: 2023-12-10
#-------------------------------------------------------------------------

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


[1] Homebrew setup
    Unlike the sibling DMGs like "LW-klayout-0.28.12-macOS-Monterey-1-qt5Brew-Rhb32Phb311.dmg,"
    this package contains the Qt5 and Python frameworks from Homebrew.
    Therefore, you don't need to install the Homebrew development environment.
    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.6 (main, Oct  2 2023, 20:14:46) \   <=== Python version may differ
        [Clang 14.0.0 (clang-1400.0.29.202)] 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.1.2-cp311-cp311-macosx_10_9_x86_64.whl.metadata (18 kB)
        Collecting scipy
          Using cached scipy-1.11.3-cp311-cp311-macosx_10_9_x86_64.whl.metadata (60 kB)
        Collecting matplotlib
          Using cached matplotlib-3.8.0-cp311-cp311-macosx_10_12_x86_64.whl.metadata (5.8 kB)
        Collecting numpy<2,>=1.23.2 (from pandas)
          Using cached numpy-1.26.1-cp311-cp311-macosx_10_9_x86_64.whl.metadata (61 kB)
        :
        :
        Successfully installed contourpy-1.1.1 cycler-0.12.1 fonttools-4.43.1 kiwisolver-1.4.5 \
                     matplotlib-3.8.0 numpy-1.26.1 packaging-23.2 pandas-2.1.2 pillow-10.1.0 \
                     pyparsing-3.1.1 python-dateutil-2.8.2 pytz-2023.3.post1 scipy-1.11.3 six-1.16.0 \
                     tzdata-2023.3
        0

        >>> quit()


[2] KLayoutHomebrew-H.app
    Optionally, drag and drop this bundle to the /Applications folder, 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.

[EOF]
