.. -*- coding: utf-8; -*-

=========
 Cygwin.
=========
.. contents::
   :local:

Installation
============

http://cygwin.com/mirrors.html
  Official mirror list.

Important packages:

* ``bash-completion`` - for human CLI.
* ``emacs-w32`` - Cygwin's Emacs with native Windows widgets!
* ``vim`` - let's have "improved" VI.
* ``aspell``, ``aspell-en`` - for spell checking inside Emacs.
* ``curl`` - for HTTP troubleshooting.
* ``wget`` - for recursive downloading, also required by ``apt-cyg``.
* VCS packages::

    mercurial git git-completion git-svn subversion fossil

* ``make`` - my favorite automation tool.
* ``the_silver_searcher`` - human ``grep``.

Configuration
=============

Run ``setup.exe``. Today you should prefer 64-bit flavor because it sould less BLODA. Add Cygwin
``/bin`` directory to your ``PATH`` env var::

  set PATH=c:\opt\cygwin\bin;%PATH%

Cygwin behavior can be altered via ``CYGWIN`` env var::

  set CYGWIN=noglob wincmdln

* ``noglob`` disable reinterpreting positional arguments native Windows application as if they
  contain shell wildcards. With ``glob`` running ``ls *`` from ``cmd`` works as if it is run from
  Unix shell.

  When I used native Emacs & Cygwin wrapper for ``hg`` default option ``glob`` broke Emacs VC mode
  because Emacs is using ``{rev}`` as one of the arguments and it was replaced by empty string when
  ``glob`` is active.

  ``noglob`` enshures that there are no any magical replacement.

* ``wincmdln`` helps during process invocation troubleshooting. Cygwin maintains own structures for
  program positional arguments so argument list is invisible to Windows programs like Process
  Monitor. The option ``wincmdln`` tells Cygwin program to copy internal structure for arguments to
  Windows managed structure making arguments visible.

https://cygwin.com/cygwin-ug-net/using-cygwinenv.html
  The ``CYGWIN`` environment variable. Available options.

The easiest way to install env var ``CYGWIN`` is via ``.reg`` file::

  [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment]
  "CYGWIN"="noglob wincmdln"

https://stackoverflow.com/questions/1494658/how-can-i-change-my-cygwin-home-folder-after-installation
  How can I change my Cygwin home folder after installation?

Set ``TMP`` and ``TEMP`` env vars without dangerous symbols in path (without spaces, etc)::

  set TMP=c:\tmp
  set TEMP=c:\tmp

Also you need to edit ``/etc/passwd`` to point to correct home path.

For Cygwin 1.7 ``/etc/nsswitch.conf`` settings is used to define user home. By default it is
``/home/%U`` so it is better to create symlink::

  $ ln -s /cygdrive/d/home /home/user

Alternatively with native Windows symlink (from build-in ``cmd`` command)::

  cmd# mklink /D c:\opt\cygwin\home\user c:\home

List of installed packages (``-c`` - check, ``-d`` - dump only)::

  $ cygcheck -c -d

Alternatively look to file content::

  /etc/setup/installed.db

In a past I work with particular code point::

  set LANG=ru_RU.cp1251

Altering ``LANG`` for anything other then ``C`` cause only problems, when you get help and error
messages in non-English. It is mostlry impossible to search for keywords, when text are translated.

Mount points
============

In Cygwin the 3rd parameter (FS type) has special meaning:

* ``cygdrive`` defines prefix to Windows disk letters like ``c:``.
* ``usertemp`` defines location of temp directory.

``/etc/fstab``::

  none    /cygdrive none binary,posix=0,user,noacl 0 0
  c:/opt/   /opt    none binary,noacl,user,posix=0 0 0
  d:/backup /backup none binary,noacl,user,posix=0 0 0
  /var     /usr/var none bind

https://cygwin.com/cygwin-ug-net/using.html#mount-table
  The Cygwin Mount Table. Description of supported keys.

Recent version of Win 10 exposes WSL distros via P9 network protocol. As Cygwin supports UNC paths
it is possible to add mount points (don't forget to create directory ``/wsl`` before mounting!)::

  //wsl$/debian /wsl/debian  ntfs binary,noacl,posix=0 0 0
  //wsl$/ubuntu /wsl/ubuntu  ntfs binary,noacl,posix=0 0 0
  //wsl$/alpine /wsl/alpine  ntfs binary,noacl,posix=0 0 0

Users
=====

Cygwin allow complex mapping Windows accounts to POSIX:

https://cygwin.com/cygwin-ug-net/ntsec.html
  POSIX accounts, permission, and security.

Modern Cygwin (v3.x) relies on ``/etc/nsswitch.conf`` for user settings. That means there are no
``/etc/passwd`` & ``/etc/group`` and user home directory and login shell are defined according to
``nsswitch.conf``::

  db_home:  /home/%U
  db_shell: /bin/bash

Earlier Cygwin used ``/etc/passwd`` & ``/etc/group`` and sometimes you were required to regenerate
them::

  $ mkpasswd -d | grep $yourlogin > /etc/passwd
  $ mkpasswd -l > /etc/passwd
  $ mkgroup -l > /etc/group

Documentation
=============

Cygwin C API man pages and user guide manuals available in ``cygwin-doc``
package.

Documentation unpacked to ``/usr/share/doc/cygwin-...`` directory.

apt-cyg package manager
=======================

``apt-cyg`` is based on ``bash``, ``wget``, ``tar``, ``gawk`` and ``bzip2``
packages and provide convenient commands for managing and queries packages::

  $ apt-cyg update
  $ apt-cyg install emacs-w32
  $ apt-cyg remove emacs-w32

Information about package and dependencies::

  $ apt-cyg show emacs-w32
  $ apt-cyg depends wget
  $ apt-cyg rdepends emacs

List installed packages::

  $ apt-cyg list

Search for package with file across installed packages::

  $ apt-cyg search stdio.h

List package files for installed packages::

  $ apt-cyg listfiles util-linux

Search for package with file through cygwin.com::

  $ apt-cyg searchall stdio.h

List all packages in ``setup.ini``::

  $ apt-cyg listall

Find package by regex::

  $ apt-cyg listall ^emacs

To switch between mirrors::

  $ apt-cyg mirror ftp://ftp.cygwinports.org/pub/cygwinports
  $ apt-cyg update
  $ apt-cyg install php

  $ apt-cyg mirror ftp://www.fruitbat.org/pub/cygwin/circa/2016/08/30/104223

  $ apt-cyg mirror http://mirrors.kernel.org/sources.redhat.com/cygwin/

Just switching mirror does not update metadata.

To change a location of directory where packages and ``setup.ini`` downloaded::

  $ apt-cyg cache
  C:\net

  $ apt-cyg cache ~/net
  Cache set to C:\home\net.

https://github.com/kou1okada/apt-cyg
  Still maintained project with extra features.
https://github.com/transcode-open/apt-cyg/
  Home page of abandoned project.
https://github.com/transcode-open/apt-cyg/issues/19
  Request to support multiply sources.
http://stackoverflow.com/questions/22411162/how-to-add-a-repository-using-apt-cyg/
  How to add a repository using apt-cyg.
https://odoepner.wordpress.com/2012/12/06/install-cygwin-and-cygwinports-packages-using-apt-cyg/
  Depricated way to install from several sources with ``-m`` option using shell
  aliases as a trick.

Cygwin bash completion
======================

Cygwin ``bash`` has extra patch that adds ``completion_strip_exe`` option::

  shopt -s completion_strip_exe

If you complete executable ``.exe`` suffix is stripped if any. That halps with ``bash-completion``
because usually comletion defined for base name without ``.exe`` suffix, like::

  complete -F _figlet figlet

https://github.com/cygwinports/bash
  7b. completion_strip_exe - using 'shopt -s completion_strip_exe'
  makes completion strip .exe suffixes.

Cygwin file permission
======================

Get list of permissions::

  $ getfacl .

rsync without problems::

  $ rsync -ar —chmod=ugo=rwX $FROM/ $TO/

https://cygwin.com/cygwin-ug-net/using-filemodes.html
  File permissions.
https://cygwin.com/cygwin-ug-net/ntsec.html
  POSIX accounts, permission, and security.
https://stackoverflow.com/questions/5828037/cygwin-sets-file-permission-to-000
  Cygwin sets file permission to 000.

Installation on Windows XP
==========================

Cygwin from v2.5.5 and Setup version 2.874 (on 25 Aug 2016) is latest version
with Windows XP support. Later versions build with dependencies on newer
syscalls and failt to run in Windows XP.

Latest mirrors avaialble at fruitbat.org:

* 32-bit: ftp://www.fruitbat.org/pub/cygwin/circa/2016/08/30/104223
* 64-bit: ftp://www.fruitbat.org/pub/cygwin/circa/64bit/2016/08/30/104235

To run setup against this mirror::

  cmd> setup.exe

``setup.exe`` available at:

* 32-bit ftp://www.fruitbat.org/pub/cygwin/setup/snapshots/setup-x86-2.874.exe
* 64-bit ftp://www.fruitbat.org/pub/cygwin/setup/snapshots/setup-x86_64-2.874.exe

Run as (``-X`` disable signature verification, ``-s <url>`` option select a
particular mirror, ``-O`` option disallow any other mirrors)::

  cmd> setup-x86.exe -X -s ftp://www.fruitbat.org/pub/cygwin/circa/2016/08/30/104223 -O

http://www.fruitbat.org/Cygwin/timemachine.html
  Description of Cygwin time machine project.
http://stackoverflow.com/questions/39479826/cygwin-2-5-2-mirror-getting-the-last-xp-release
  Question about Cygwin old mirror.
http://superuser.com/questions/1132000/is-it-still-possible-to-get-cygwin-for-xp
  Question about Cygwin old mirror.
http://cygwin-xp.portfolis.net/
  Another old mirror.

Cygwin ports
============

This project provides Cygwin binary and source packages for a large variety of programs and
libraries, including the GNOME  and KDE desktop environments

http://cygwin-ports.sourceforge.net/
  Newest home of the Cygwin Ports project.
http://sourceware.org/cygwinports/
  Home page.
http://cygwinports.blogspot.com
  Official blog.
https://github.com/cygwinports
  cygport scripts to compile cygwinports
https://github.com/cygwinports/cygport
  Source packaging tool for Cygwin
https://cygwinports.github.io/cygport
  Cygport Reference Manual.

Which Cygwin version you run?
=============================
::

  $ uname -r
  1.7.7(0.230/5/3)
  $ cygcheck -c cygwin
  Cygwin Package Information
  Package              Version        Status
  cygwin               1.7.7-1        OK

Rebase dll
==========

In order to Cygwin to maintain ``fork()`` syscall it should preserve same
logical base address for dll to be able to share library between child and
parent process. It was done via special hints in dlls.

With new version of Cygwin software or external Windows libraries (AntiVirus may
inject its their libraries into Cygwin process address space) it may happen that
new library is overlapped with existing.

There is ``rebase`` utility that changes base address hints for dll.

You should finish all Cygwin processes in order to ``rebase`` to succeed.

You may trigger automatic rebase of all packages in next run of ``setup.exe``
with::

  $ rebase-trigger full

Read more at:

* ``/usr/share/doc/rebase/README``
* ``/usr/share/doc/Cygwin/_autorebase.README``

https://cygwin.com/faq/faq.html#faq.using.fixing-fork-failures
  How do I fix fork() failures?
https://chromium.googlesource.com/chromium/src/+/master/docs/cygwin_dll_remapping_failure.md
  Handling repeated failures of rebaseall to allow cygwin remaps.

Running X Window.
=================
::

  $ XWin -multiwindow&

or::

  $ XWin -clipboard -silent-dup-error -xkblayout "us,ru" -xkboptions "grp:caps_toggle"&

To start X application you must set 'DISPLAY'::

  $ DISPLAY=:0 xterm&

Working with packages.
======================

Installed package list with versions.
-------------------------------------
::

  $ cygcheck -c -d

List of package files.
----------------------
::

  $ cygcheck -l pkg-name

Search package by containing file (only under installed packages).
------------------------------------------------------------------
::

  $ cygcheck -f full-path-to-file

Search packages by containing path (only under installed packages).
-------------------------------------------------------------------
::

  $ for f in /etc/setup/*.lst.gz; do gzip -c -d $f | grep $WORD  2>&1 >/dev/null && { echo $f; break; } || :; done

Search for package.
-------------------

If you have file name or regex use (need internet connection)::

  $ cygcheck -p REGEX

cygcheck use such link::

  http://cygwin.com/cgi-bin2/package-grep.cgi?grep=REGEX

Cygwin installation info.
=========================
::

  $ uname -a
  $ cygcheck -s -r

Cygwin acronyms.
================

http://www.cygwin.com/acronyms
  One encounters all sorts of acronyms on the Cygwin mailing lists.

Check dll dependency.
=====================
::

  $ ldd my.dll
  $ ldd my.exe
  $ cygcheck ./my.dll
  $ cygcheck ./my.exe

Cygwin alternatives.
====================

http://www.suacommunity.com/SUA.aspx
  Subsystem for Unix-based Applications and Services for Unix