mlucas/README

-*- org -*-

[[https://www.mersenneforum.org/mayer/README.html][Mlucas 17.1]]

mlucas is an open-source (and free/libre) program for performing Lucas-Lehmer
test on prime-exponent Mersenne numbers, that is, integers of the form
2 ^ p - 1, with prime exponent p. In short, everything you need to search for
world-record Mersenne primes! It has been used in the verification of various
Mersenne primes, including the 45th, 46th, 48th, 49th and 50th found Mersenne
prime.

You may use it to test any suitable number as you wish, but it is preferable
that you do so in a coordinated fashion, as part of the Great Internet Mersenne
Prime Search ([[https://www.mersenne.org/primes/][GIMPS]]).


* Installation

  Run

  #+BEGIN_SRC
  ./configure
  make
  make check
  make install
  #+END_SRC

  to complete the installation.

  Normally, the configure script should guess your system configuration.
  However, you can always override it by passing flags to the configure script.

  Running test is optional. Run it if you want to be on the safe side.

  Below is a summary of notable options understood by the configure script.
  You can see all options by running ~./configure -h~.

* Notable Options

System types:
  --host=HOST       cross-compile to build programs to run on HOST [BUILD]

Optional Features:
  --enable-silent-rules   less verbose build output (undo: "make V=1")
  --disable-silent-rules  verbose build output (undo: "make V=0")
  --disable-threads       disable thread support detection
  --enable-mlucas-default-path
                          set MLUCAS_DEFAULT_PATH (unset by default) to
                          "$HOME/.mlucas.d/"
  --enable-compiler-features[=feature[,...]]
                          list of compiler features to be detected (default to
                          optimization,debugging,hardening if none is given)
  --disable-compiler-features
                          disable compiler features detection
  --enable-builds[=build[,...]]
                          list of build variants to be enabled (default to
                          generic-c,sse2 for x86 host,
                          generic-c,sse2,avx,avx2,avx512 for x86_64 host if
                          none is given)
  --enable-verbose-compiler
                          ignored and will be removed in the future
  --enable-instruction    ignored and will be removed in the future
  --enable-MLUCAS-DEFAULT-PATH
                          ignored and will be removed in the future

* Usage

[[https://www.mersenneforum.org/mayer/README.html][Online documentation]]
is available.
To show the help text, run ~./mlucas -h~.
After installation, you can run ~man mlucas~ to show the man page.

* Licensing

  Most of the files are licensed under the GNU General Public License version 2
  or later. Other files are under permissive licenses or in the public domain.
  All files except empty files or generated data should have a license header
  or footer. If not, please send a bug report (see [[Bugs]] for details).

  See file:COPYING for details regarding licensing.

* Bugs

  The argument parser is buggy. The relative position of arguments is relevant
  to mlucas, the order of arguments in SYNOPSIS in mlucas(1) should be followed
  to avoid confusing the parser. Only 100, 1000 and 10000 are supported for
  -iters flag. However, the parser will not reject unsupported arguments. Using
  unsupported arguments for -iters flag may trigger strange behaviour.

  For problems regarding the program mlucas, please contact the author
  [[mailto:ewmayer@aol.com][Ernst W. Mayer]].
  For installation and documentation related problems regarding this package
  and this file:README, please contact
  [[mailto:alexvong1995@gmail.com][Alex Vong]].

  See BUGS section in mlucas(1) for details.

* ROADMAP

  - simplify to reduce maintenance burden
    + replace autogen by guile
    + remove useless, duplicate files

  - documentation
    + use org-mode in various plain text files
    + replace pod with something lispy

  - configure script
    + use sane defaults
    + remove normal cflags, tricky flags
    + detect if compilers support certain flags in configure script

  - respect freedesktop standard
    + use file:~/.local/share/mlucas/ instead of file:~/.mlucas.d/

  - revert previous changes
    + replace use of ~mlucas_fopen()~ by ~fopen()~
    + and use ~chdir()~ instead
    + replace use of ~system("mkdir -p ...")~ with ~mkdir_p()~ from busybox
    + hence we can remove ~shell_quote()~ and friends

  - find out memory bugs
    + asan
    + ubsan
    + valgrind

* Copyright

  README - readme for Mlucas
  Copyright (C) 2015-2019  Alex Vong

  This program is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 2
  of the License, or (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software Foundation,
  Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.