Additional documentation and examples
=====================================

Please read the links on https://www.mirbsd.org/ksh-chan.htm and peek at:
https://evolvis.org/plugins/scmgit/cgi-bin/gitweb.cgi?p=shellsnippets/shellsnippets.git


Reporting bugs
==============

Please report only packaging bugs in the Debian BTS. Report code
bugs, but *especially* feature requests, upstream, either via IRC
or mailing list or, if it must be, at Launchpad:

* #!/bin/mksh (or #ksh) IRC channel
  at irc.freenode.net (Port 6697 SSL, 6667 unencrypted)

* mksh mailing list <miros-mksh@mirbsd.org>
  (does not require subscription to post)
  archived at http://news.gmane.org/gmane.os.miros.mksh and others

* https://launchpad.net/mksh


Notes for the mksh binary package
=================================

* After installation, it is strongly recommended to copy the file
  /etc/skel/.mkshrc into your home directory to get a nicer prompt,
  pushd/popd/dirs functionality, some aliases, etc. (you can then
  customise it; reading the manual page also often helps).
  Note that /etc/skel/.mkshrc sources /etc/mkshrc (which is the
  upstream-provided file) by default and contains some (commented
  out) examples to set the locale and editor. Change the file once
  copied into the home if you do not want this.

* The MirBSD Korn Shell provides a workable /bin/sh for Debian;
  installation however is not automatic due to Debian #540512 (a
  bug in dash). It is strongly recommended to use its “legacy”
  flavour for this, as it uses the host “long” C type for integer
  arithmetics, following POSIX. Use these commands:
  $ sudo ln -sf lksh /bin/sh
  $ sudo ln -sf mksh.1.gz /usr/share/man/man1/sh.1.gz
  This will install the mksh manpage for sh(1) since it explains
  better what the shell is actually about; lksh(1) contains only
  a short summary of differences.
  Please note that lksh, as opposed to mksh, is not suited for
  interactive use (but no regression from dash which also isn’t).

* The /bin/lksh binary is used to run legacy ksh88 and pdksh scripts
  only. It was not suitable as /bin/sh before Debian mksh 46-2, nor
  is it intended for interactive use. It only has a printf(1) builtin
  starting with mksh 46-2 in Debian. It however is used to provide
  pdksh as transitional package. It will not be registered with the
  menu system or set up as login shell. Also, do not use the pdksh
  compatibility symlink as login shell.

* /bin/mksh is built with the following options:
  - extra hardening flags: +all
  - glibc (dynamically linked)
  - calling as sh or -sh invokes "set -o posix -o sh"

* /bin/mksh-static is built with the following options:
  - extra hardening flags: +all but no PIE
    (position independent code), as this is a static executable
  - glibc, if cross-built or running the testsuite is disabled;
    otherwise klibc if available and working, otherwise dietlibc
    if available and working, otherwise glibc
  - note that the stack protector is disabled on dietlibc, klibc
    due to limitations in those operating environments
  - calling as sh or -sh invokes "set -o posix -o sh"
  - -DMKSH_SMALL
  - no locale support; uses getenv on LANG/LC_CTYPE/LC_ALL

* /bin/lksh is built with the following options:
  - extra hardening flags: +all (no PIE if dietlibc or klibc is used)
  - dietlibc or klibc (under similar conditions as /bin/mksh-static)
    or, otherwise, glibc (dynamically linked)
  - the printf builtin
  - calling as sh or -sh invokes "set -o posix -o sh"
  - no locale support; uses getenv on LANG/LC_CTYPE/LC_ALL

* The following testsuite failures, especially on the autobuilder
  network, are harmless and can be ignored:
  - utf8bom-2 (mksh-full only)
  - heredoc-tmpfile-8 (on slow machines)
  Failures in dollar-quoted-strings or history-subst-4 (#523086)
  are errors in dietlibc on the respective architectures. These
  have been fixed past Debian squeeze and *buntu oneiric but may
  still occur on backports; except history-subst-4 [hppa], they
  are tested for, and on failure rebuilt against glibc, on non-
  cross non-nocheck builds.

Details (generated during package build) can be found below:

