#-------------------------------------------------------------------------
# File: MacPortsUser-ReadMeFirst.txt
#                              in macbuild/Resources/script-bundle-P.zip
#
# Last modified: 2024-09-23
#-------------------------------------------------------------------------

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


[1] MacPorts setup
    First, you must set up the MacPorts environment to use this package.
    Referring to https://www.macports.org/install.php, follow the three steps for Quickstart.
      1. Install Xcode and the Xcode Command Line Tools
      2. Agree to Xcode license in Terminal: sudo xcodebuild -license
      3. Install MacPorts for your version of the Mac operating system:
              o macOS Sequoia v15
              o macOS Sonoma v14
              o macOS Ventura v13
              o macOS Monterey v12
              o Older OS? See here.

    Next, install some ports. qt5, ruby33, python312, and libgit2 are mandatory.
        $ sudo port install coreutils
        $ sudo port install findutils
        $ sudo port install qt5
        $ sudo port install ruby33
        $ sudo port install python312
        $ sudo port install py312-pip
        $ sudo port install libgit2

        $ sudo port select --set python3 python312
        $ sudo port select --set python  python312
        $ sudo port select --set pip3    pip312
        $ sudo port select --set pip     pip312
        $ sudo port select --set ruby    ruby33

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


[2] KLayoutPorts.app
    This bundle is for those with the MacPorts environment under /opt/local.
    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] KLayoutPorts.app.Bash
    This file is the source Bash script of the "KLayoutPorts.app" bundle.
    You can refer to this script and use the "Automator.app" tool to create your script bundle
    from scratch. See the "KLayoutPorts.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
    This LW*.dmg contains the KLayout standalone Python package (klayout*.whl) compliant with the base Python system.
    Refer to "pymod-pip3-mp312.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]
