comment -*- mode: text -*-

How to build & install libvte compatible library using mlterm engine.

* Requirements
  o vte library and headers
  o gtk+ 2.x, 3.x or 4.x
  o terminal emulators or other applications using libvte 
    (gnome-terminal, roxterm, synaptic or etc)

* Supported API
  vte 0.84

* Build
  $ ./configure (--with-type-engine=cairo --with-imagelib=gdk-pixbuf --enable-pty-helper \
    --with-gtk=2.0 ...)
    - Xft and cairo are not required, but strongly recommended because it is
     impossible to change font settings from preferences menu without them.
     In addition, you should choose what gtk+ and pango installed to your
     system depend on such as gdk-pixbuf.
    - If you want to use gnome-pty-helper, specify --enable-pty-helper option and
     place gnome-pty-helper (or its symbolic link file) at ${libexecdir}/mlterm/.
    - If libvte on your system depends on gtk+-2.x, specify --with-gtk=2.0 option.
      - libvte.so.9 => gtk+-2.x
      - libvte2_90.so.9 and libvte-2.91.so.9 => gtk+-3.0
      - libvte-2.91-gtk4.so.0 => gtk-4.0
  $ make
  $ make vte (== "cd gtk; make")

* Build in MSYS2/MinGW-w64
  (It supports gtk-3.x alone for now)
  1) Copy /usr/include/vte-2.91 in Linux to /mingw64/include
  2) Copy /usr/lib/pkgconfig/vte-2.91.pc to /mingw64/lib/pkgconfig
     (Replace 'prefix' with /mingw64)
  3) Build
     CFLAGS="-Wall -g -O2" ./configure --prefix=/mingw64 --disable-ssh2
     make
     make vte

* Install (Replace official libvte)
  $ cd baselib ; make install-la
  $ cd encodefilter ; make install-la
  $ make install-vte (== "cd gtk ; make install")
  $ ln -sf [where libvte of mlterm is installed]/libvte.so.9 \
           [where official libvte is installed]/libvte.so.9
    or
    ln -sf [where libvte of mlterm is installed]/libvte2_90.so.9 \
           [where official libvte is installed]/libvte2_90.so.9
    or
    ln -sf [where libvte of mlterm is installed]/libvte-2.91.so.9 \
           [where official libvte is installed]/libvte-2.91.so.9

* Start terminal emulators using libvte
  $ gnome-terminal (roxterm, synaptic or etc)
  => mlterm inside gnome-terminal is started.

* Notice
  o Because it is mlterm that works inside gnome-terminal or etc,
    - Configuration files in ~/.mlterm/ are applied. (*)
    - Configuration protocol (like '$ mlcc [key] [value]') is mostly available.
    - Pressing Ctrl+Button3 shows 'mlconfig' menu.

    (*) Following configurations are invalidated by gnome-terminal or etc in startup.
       - 'DEFAULT' settings in ~/.mlterm/(v)(aa)font
       - 'bel_mode', 'fg_color', 'bg_color', 'cursor_bg_color', 'wall_picture',
         'use_transbg', 'alpha', 'encoding' and 'blink_cursor' options
	 in ~/.mlterm/main

  o Following functions which normal mlterm provides are not available.
    - Daemon mode
    - Multiple ptys using Ctrl+F1 / Ctrl+F2 / Ctrl+F3
    - Vertical writing mode
    - 'screen_width_ratio' option
    - 'inner_border' option
    - 'use_urgent_bell' option

  o It is recommended to specify the same font to configuration of gnome-terminal
    or etc and ~/.mlterm/aafont so as not to load excessive fonts.
    ex) - gtkterm2
    ~/.gtkterm2rc    => terminalFont=Terminal 14
    ~/.mlterm/aafont => DEFAULT=Terminal 14

  o libvte compatible library of mlterm 3.9.1 or later supports XInput2.
    But if keyboard and mouse don't work correctly, try to set "GDK_CORE_DEVICE_EVENTS"
    environmental variable which disables XInput2.

    $ export GDK_CORE_DEVICE_EVENTS=1

  o The scrollbar is not displayed in gtk4.

  o Unsupported vte api functions
    - vte_terminal_copy_primary
    - vte_terminal_set_font_scale
    - vte_terminal_get_font_scale
    - vte_terminal_set_scroll_background
    - vte_terminal_set_scroll_on_keystroke
    - vte_terminal_set_rewrap_on_resize
    - vte_terminal_get_rewrap_on_resize
    - vte_terminal_set_color_highlight
    - vte_terminal_set_color_highlight_foreground
    - vte_terminal_set_background_tint_color
    - vte_terminal_set_cursor_shape
    - vte_terminal_get_font
    - vte_terminal_set_allow_bold
    - vte_terminal_get_allow_bold
    - vte_terminal_set_mouse_autohide
    - vte_terminal_get_mouse_autohide
    - vte_terminal_get_text
    - vte_terminal_get_text_include_trailing_spaces
    - vte_terminal_get_text_range
    - vte_terminal_match_add_gregex (incomplete)
    - vte_terminal_match_set_cursor
    - vte_terminal_match_set_cursor_type
    - vte_terminal_match_set_cursor_name
    - vte_terminal_match_remove
    - vte_terminal_match_check (incomplete)
    - vte_terminal_match_check_event
    - vte_terminal_search_set_wrap_around
    - vte_terminal_search_get_wrap_around
    - vte_get_user_shell
    - vte_terminal_get_status_line
    - vte_terminal_get_child_exit_status
    - vte_terminal_set_alternate_screen_scroll
    - vte_terminal_set_geometry_hints
    - vte_pty_new_foreign_sync
    - vte_pty_close
    - vte_terminal_set_input_enabled
    - vte_terminal_get_current_directory_uri
    - vte_terminal_get_current_file_uri
    - vte_regex_jit
    - vte_terminal_match_add_regex
    - vte_terminal_event_check_regex_simple
    - vte_terminal_set_allow_hyperlink
    - vte_terminal_hyperlink_check_event
    - vte_terminal_set_bold_is_bright
    - vte_terminal_set_cell_width_scale
    - vte_terminal_set_cell_height_scale
    - vte_terminal_set_text_blink_mode
    - vte_set_test_flags
    - vte_terminal_get_color_background_for_draw
    - vte_regex_substitute
    - vte_terminal_set_enable_bidi
    - vte_terminal_set_enable_shaping
    - vte_get_encodings
    - vte_get_encoding_supported
    - vte_terminal_event_check_regex_array
    - vte_terminal_set_enable_sixel

  o Unsupported vte signals and properties
    - signals
      "eof"
      "commit"
      "emulation-changed"
      "contents-changed"
      "cursor-moved"
      "deiconify-window"
      "iconify-window"
      "raise-window"
      "lower-window"
      "refresh-window"
      "restore-window"
      "maximize-window"
      "resize-window"
      "move-window"
      "status-line-changed"
      "increase-font-size"
      "decrease-font-size"
      "text-modified"
      "text-inserted"
      "text-deleted"
      "text-scrolled"
      "copy-clipboard"
      "paste-clipboard"

    - class property
      "allow-bold"
      "background-image-file"
      "background-image-pixbuf"
      "background-opacity"
      "background-saturation"
      "background-tint-color"
      "background-transparent"
      "backspace-binding"
      "cursor-blink-mode"
      "cursor-shape"
      "delete-binding"
      "emulation"
      "encoding"
      "pointer-autohide"
      "pty"
      "scroll-background"
      "scroll-on-keystroke"
      "scroll-on-output"
      "word-chars"
      "visible-bell"

* Tested terminals using vte.
  o gnome-console 50.0 on Arch Linux    ... OK except transparency
  o gnome-terminal 3.60.0 on Arch Linux ... OK except transparency
  o gnome-terminal 2.16.0 on CentOS 5   ... OK
  o roxterm 3.11.1 on Arch Linux        ... OK
  o lxterminal 0.4.1 on Arch Linux      ... OK
  o sakura 3.8.9 on Arch Linux          ... OK
  o terminator 2.1.5 on Arch Linux      ... OK

  Following platforms are not actually tested by developers, but were tested
  in the past.
  o gnome-terminal 3.46.7 on Arch Linux
  o gnome-terminal 3.42.1 on Arch Linux
  o gnome-terminal 3.38.1 on Arch Linux
  o gnome-terminal 3.34.2 on Arch Linux
  o gnome-terminal 3.32.2 on Arch Linux
  o gnome-terminal 3.30.2 on Arch Linux
  o gnome-terminal 3.28.2 on Arch Linux
  o gnome-terminal 3.26.2 on Arch Linux
  o gnome-terminal 3.24.2 on Arch Linux
  o gnome-terminal 3.16.2 on Ubuntu 15.10
  o gnome-terminal 3.14.2 on Ubuntu 15.04
  o gnome-terminal 3.15.0 on Ubuntu 14.10
  o gnome-terminal 3.6.2 on Ubuntu 14.10
  o gnome-terminal 3.6.2 on Ubuntu 13.10
  o gnome-terminal 3.6.1 on Ubuntu 13.04
  o gnome-terminal 3.6.0-0ubuntu1 on Ubuntu 12.10
  o gnome-terminal 3.4.1.1-0ubuntu1 on Ubuntu 12.04
  o gnome-terminal 3.0.1 on Ubuntu 11.10
  o gnome-terminal 2.32.0 on Ubuntu 10.10
  o gnome-terminal 3.22.0 on Fedora 25
  o gnome-terminal 3.20.2 on Fedora 24
  o lxterminal 0.4.0 on Arch Linux
  o lxterminal 0.3.2 on Arch Linux
  o roxterm 3.3.2 on Arch Linux
  o roxterm 3.1.4 on Ubuntu 15.10
  o roxterm 2.9.5 on Ubuntu 15.04
  o roxterm 2.8.2 on Ubuntu 14.10
  o roxterm 2.7.2 on Ubuntu 13.10
  o roxterm 2.6.5-1 on Ubuntu 13.04
  o roxterm 1.22.2-1 on Ubuntu 12.04
  o roxterm 1.22.2 on Ubuntu 11.10
  o roxterm 1.18.5 on Ubuntu 10.10
  o roxterm 1.18.5 on NetBSD 3.0.1
  o roxterm 3.3.2 on Fedora 25
  o roxterm 3.3.2 on Fedora 24
  o synaptic 0.80.2 on Ubuntu 13.10
  o synaptic 0.80 on Ubuntu 13.04
  o synaptic 0.75.12build1 on Ubuntu 12.10
  o synaptic 0.75.9ubuntu1 on Ubuntu 12.04
  o synaptic 0.63.1 on Ubuntu 10.10
  o evilvte 0.5.1 on Ubuntu 13.10
  o evilvte 0.5.1-1 on Ubuntu 13.04
  o evilvte 0.5.0-1 on Ubuntu 12.04
  o evilvte 0.4.8 on Ubuntu 11.10
  o evilvte 0.4.9pre4 on NetBSD 3.0.1
  o sakura 3.8.4 on Arch Linux
  o sakura 3.8.3 on Arch Linux
  o sakura 3.7.1 on Arch Linux
  o sakura 3.6.0 on Arch Linux
  o sakura 3.1.5 on Ubuntu 15.04
  o sakura 3.1.0 on Ubuntu 13.10
  o sakura 3.0.4-2 on Ubuntu 13.04
  o sakura 3.0.3-2 on Ubuntu 12.04
  o sakura 2.4.2 on Ubuntu 11.10
  o sakura 2.3.8 on Ubuntu 10.10
  o lxterminal 0.1.11 on Ubuntu 13.10
  o lxterminal 0.1.11-4ubuntu2 on Ubuntu 13.04
  o lxterminal 0.1.11-2ubuntu1 on Ubuntu 12.04
  o lxterminal 0.1.11 on Ubuntu 11.10
  o gtkterm2 0.2.3 on NetBSD 3.0.1
  o terminator 2.1.2 on Arch Linux
  o terminator 2.1.1 on Arch Linux
  o terminator 1.92 on Arch Linux
  o terminator 1.91 on Arch Linux
