From f1ea5d3fc7d0d7a92efd2585f19226af66bdc98a Mon Sep 17 00:00:00 2001 From: polos Date: Mon, 24 Jul 2017 12:01:55 +0200 Subject: [PATCH] change READMEs from TXT to MD --- README-1.md | 341 ++++++++++++++++++++++++++++++++++++++ README-1.txt | 283 ------------------------------- README-2-REBUILD.md | 53 ++++++ README-2-REBUILD.txt | 47 ------ README-3-OPTIONAL.md | 55 ++++++ README-3-OPTIONAL.txt | 51 ------ README-4-KNOWN-ISSUES.md | 17 ++ README-4-KNOWN-ISSUES.txt | 11 -- 8 files changed, 466 insertions(+), 392 deletions(-) create mode 100644 README-1.md delete mode 100644 README-1.txt create mode 100644 README-2-REBUILD.md delete mode 100644 README-2-REBUILD.txt create mode 100644 README-3-OPTIONAL.md delete mode 100644 README-3-OPTIONAL.txt create mode 100644 README-4-KNOWN-ISSUES.md delete mode 100644 README-4-KNOWN-ISSUES.txt diff --git a/README-1.md b/README-1.md new file mode 100644 index 0000000..641918c --- /dev/null +++ b/README-1.md @@ -0,0 +1,341 @@ + +*EQL5 is a (extended) Qt5 port of EQL/Qt4* + +--- + +[wiki](https://gitlab.com/eql/EQL5/wikis/home) +[mailing list](https://groups.google.com/group/eql-user/topics) +contact: gmail, polos.ruetz + +**Many thanks** to the users of the eql-user mailing list and to private mail +contacts for your contributions and testing! + + + +Build (for the impatient) +------------------------- + +In `src/` do: + +``` + $ ecl -shell make + $ qmake eql5.pro # comment out all modules you don't need + $ make + $ sudo make install # Unix only +``` + +Now you should be able to run `eql5`. + +If there are problems, or you want more info, see detailed instructions below. + +N.B. If the above runs, please don't forget to integrate the +**wrapper functions**, see `README-3-OPTIONAL`, needed for serious development. + + + +Tested with: +------------ + +*Linux* (development platform), with both gcc and clang: + +* ECL 16.1.2 +* Qt 5.5.1 (with module 'webkit') +* Qt 5.8 (with module 'webengine') + +*Windows/32*: + +* MSVC 2010, MinGW 4.9 +* ECL git 2017-02 / 32 bit +* Qt 5.5.1 / 32 bit (precompiled from qt.io archives; contains WebKit) + +*Windows/64*: + +* MSVC 2015 +* ECL git 2016-11 / 64 bit (see flag in Makefile) +* Qt 5.7 / 64 bit (precompiled from qt.io archives; WebKit is not included) + +*macOS*: + +* not tested personally, but has been reported to work (with clang) + +-- + +MinGW note: in order to build successfully, I needed to: + +* change a typedef in `ecl.h` (after building ECL); see compile error; +* comment out all offending lines of module :quick; see SGTexture related + linker errors; the source files are in `eql5/src/gen/quick/`; + + + +Requirements +------------ + +* ECL (both threads & unicode enabled, as by default) +* Qt >= 5.5 + +QtWebKit note: + +If you want QtWebKit included in the official downloads from qt.io archives, +you need to choose Qt 5.5, and not later versions! +QtWebKit will continue to work with versions > 5.5, but it has to be +compiled manually (which is not fun). +QtWebKit has a better, more native integration with Qt than QtWebEngine, see +for example QWebElement, which doesn't exist in QtWebEngine. + + + +Prepare +------- + +Install the ECL sources, and build it from the sources (ECL needs to be built +with the same compiler you'll use to compile EQL5). + +Just use the standard configuration of ECL (both threads & unicode enabled). + +Download Qt5 from here (pay attention to choose the version compiled with the +same compiler you'll use to compile EQL5): + +[https://download.qt.io/archive/qt/](https://download.qt.io/archive/qt/) + +Qt4/Qt5 note: + +You can have both old EQL (Qt4) and EQL5 (Qt5) installed in parallel (exe and +lib names differ). + +If you have both Qt4 and Qt5 installed, you can use the following environment +variable to switch between the both on Unix (which requires the different Qt +`bin/` directories to be in `PATH`): + +``` + $ export QT_SELECT=5 +``` + +Please note that you need to build EQL5 in a path where you will keep it (you +can't move around the whole file tree later, since the build path needs to be +hard-coded in the executable). + + + +Build +----- + +(N.B. for rebuilding, please see `README-2-REBUILD`) + +*Windows* + +You first need to adapt the file `src/windows.pri` (include & library paths). + +You also should add your eql5 directory (for eventual C++ modules), e.g: + +``` + INCLUDEPATH += ... c:/eql5/src + LIBS += ... -Lc:/eql5 +``` + +Since EQL requires the C compiler anyway (not the bytecode compiler), you +should put this line in your `~/.eclrc`: + +``` + (require :cmp) +``` + +*MSVC* + +Substitute `make` with `nmake`. + +*MinGW* + +If `make` is stuck in an infinite loop of creating the `Makefile`, just +remove the line 'include(windows.pri)' from your `*.pro` file, setting +eventually needed paths in your `~/.profile` instead. + +### 1) Build Lisp lib + +``` + $ cd src + $ ecl -shell make.lisp +``` + +### 2) Build C++ lib, exe, modules + +Edit `eql5.pro` and comment out all modules you don't need. +Then run: + +``` + $ qmake eql5.pro + $ make + $ sudo make install # Unix only +``` + +This will build the shared library, the executable and the modules. + +If you ran `make install`, you'll find the installed files here: + +``` + /usr/local/bin/ + /usr/local/lib/ + /usr/local/include/eql5/ +``` + +### 3) Environment + +*Linux* + +N.B. skip this if you did `sudo make install` +You need to create links to EQL5, something like: + +``` + $ cd /usr/lib + $ sudo ln -s ~/eql5/libeql5.so.1 libeql5.so.1 + $ cd /usr/bin + $ sudo ln -s ~/eql5/eql5 eql5 +``` + +*macOS* + +N.B. skip this if you did `sudo make install` +You need to create links to EQL5, something like: + +``` + $ cd /usr/local/lib + $ sudo ln -s ~/eql5/libeql5.1.dylib libeql5.1.dylib + $ cd /usr/local/bin + $ sudo ln -s ~/eql5/eql5.app/Contents/MacOS/eql5 eql5 +``` + +*Windows* + +Add your EQL5 directory to the `Path` environment variable, see: +<Control Panel:System:Advanced:Environment Variables> + + + +Run +--- + +You can run a simple interactive REPL UI doing: + +``` + $ eql5 -qgui +``` + +To run a Lisp file without top-level, do: + +``` + $ eql5 examples/2-clock +``` + +(If you don't see the application window, it might be in the background. +Use your taskbar to show it.) + +If you start the EQL5 executable without arguments, it will start the usual ECL +top-level (without processing Qt events). + +To *not* load `~/.eclrc` on startup, do: + +``` + $ eql5 -norc +``` + +To quit the tool, do: + +``` + (eql:qquit) ; or + (eql:qq) +``` + +In order to run (sort of) a top-level processing Qt events, do: + +``` + $ eql5 -qtpl +``` + +Note: + +If you want to use `ecl-readline` together with `-qtpl`, just compile +`lib/ecl-readline.lisp` (which depends on the **readline** C library). +It will then be loaded automatically on startup: + +``` + $ cd ~/eql5/lib + $ ecl -compile ecl-readline.lisp +``` + +N.B: Using readline, you will often need to `reset` (command) your +console/shell after EQL5 finished working, especially during development +time or other exits than `(eql:qquit)`. +An alias in `~/.bashrc` can help to make this less annoying, since you might +not see the command while typing: + +``` + $ alias r=reset +``` + + + +Qt modules +---------- + +(`help`, `multimedia`, `network`, `quick`, `sql`, `svg`, `webengine`, `webkit`) + +N.B. skip this if you already built from `eql5.pro` (see above) +To build an EQL5 module (corresponding to a Qt module), do the following in +`src/`: + +``` + $ qmake module_.pro # e.g. qmake module_network.pro + $ make + $ sudo make install # Unix only +``` + +*Linux, macOS* + +(N.B. skip this if you did `sudo make install`) +You need to create links to the modules, see EQL5 shared library above. + +In Lisp, use function `qrequire` to load a module: + +``` + (qrequire :network) +``` + + + +Tips +---- + +You might want to put this in your `~/.eclrc` file: + +``` + #+eql + (setf eql:*qtpl* t ; same as -qtpl + eql:*break-on-errors* t) +``` + +It is **highly recommended** to integrate the wrapper functions, see +`README-3-OPTIONAL`. +This will make all Qt functions real Lisp functions, which also means symbol +tab-completion, both in Emacs/Slime and with `ecl-readline`. + +Please see also example `examples/X-extras/CLOS-encapsulation.lisp` for +encapsulation of Qt classes in Lisp classes or structs (that is, Lisp classes +that behave like a Qt class if passed to Qt functions). + + + +Notes +----- + +For additional information see `doc/index.html`. + + + +License +------- + +MIT + +For `make-qimage` (contributed by Mark Cox), please see +`LICENSE-MAKE-QIMAGE.txt`. + diff --git a/README-1.txt b/README-1.txt deleted file mode 100644 index 97fa4a4..0000000 --- a/README-1.txt +++ /dev/null @@ -1,283 +0,0 @@ -******************************************** -* EQL5 is a (extended) Qt5 port of EQL/Qt4 * -******************************************** - -# wiki: http://gitlab.com/eql/EQL5/wikis/home -# mails: http://groups.google.com/group/eql-user/topics -# contact: gmail, polos.ruetz -# -# MANY THANKS to the users of the eql-user mailing list and to private mail -# contacts for your contributions and testing! - - - -BUILD (for the impatient) -===== - -In src/ do: - - ecl -shell make - qmake eql5.pro (comment out all modules you don't need) - make - sudo make install (Unix only) - -Now you should be able to exec 'eql5'. - -If there are problems, or you want more info, see detailed instructions below. - - - -TESTED WITH -=========== - - Linux (development platform), with both gcc and clang: - ECL 16.1.2 - Qt 5.5.1 (with module 'webkit') - Qt 5.8 (with module 'webengine') - - Windows: - MSVC 2010, MinGW 4.9*: - ECL git 2017-02 / 32 bit - Qt 5.5.1 / 32 bit (precompiled from qt.io archives; contains WebKit) - - MSVC 2015 - ECL git 2016-11 / 64 bit (see flag in Makefile) - Qt 5.7 / 64 bit (precompiled from qt.io archives; WebKit is not included) - - OSX: - not tested personally, but has been reported to work (with clang) - - --- - - *) to successfully build with MinGW, I needed to: - - change a typedef in "ecl.h" (after building ECL); see compile error; - - comment out all offending lines of module :quick; see SGTexture related - linker errors; the source files are in "eql5/src/gen/quick/"; - - - -REQUIREMENTS -============ - - * ECL (both threads & unicode enabled, as by default) - * Qt >= 5.5 - - QtWebKit note: - If you want QtWebKit included in the official downloads from qt.io archives, - you need to choose Qt 5.5, and not later versions! - QtWebKit will continue to work with versions > 5.5, but it has to be - compiled manually (which is not fun). - QtWebKit has a better, more native integration with Qt than QtWebEngine, see - for example QWebElement, which doesn't exist in QtWebEngine. - - - -PREPARE -======= - -Install the ECL sources, and build it from the sources (ECL needs to be built -with the same compiler you'll use to compile EQL5). - -Just use the standard configuration of ECL (both threads & unicode enabled). - -Download Qt5 from here (pay attention to choose the version compiled with the -same compiler you'll use to compile EQL5): - - https://download.qt.io/archive/qt/ - -Qt4/Qt5 note: - - You can have both old EQL (Qt4) and EQL5 (Qt5) installed in parallel (exe and - lib names differ). - - If you have both Qt4 and Qt5 installed, you can use the following environment - variable to switch between the both on Unix (which requires the different Qt - 'bin/' directories to be in PATH): - - export QT_SELECT=5 - -Please note that you need to build EQL5 in a path where you will keep it (you -can't move around the whole file tree later, since the build path needs to be -hard-coded in the executable). - - - -BUILD -===== - -(N.B. for rebuilding, please see README-2-REBUILD.txt) - - [Windows] - You first need to adapt the file 'src/windows.pri' (include & library - paths). - - You also should add your eql5 directory (for eventual C++ modules), e.g: - INCLUDEPATH += ... c:/eql5/src - LIBS += ... -Lc:/eql5 - - Since EQL requires the C compiler anyway (not the bytecode compiler), you - should put this line in your '~/.eclrc': - (require :cmp) - - [MSVC] - Substitute make with nmake. - - [MinGW] - If 'make' is stuck in an infinite loop of creating the 'Makefile', just - remove the line 'include(windows.pri)' from your '*.pro' file, setting - eventually needed paths in your '~/.profile' instead. - - [OSX] - To force creation of a Makefile (instead of an Xcode project), use this - flag: - qmake -spec macx-g++ - -1) Change to src/ and run: - - ecl -shell make.lisp - -2) Edit 'eql5.pro' and comment out all modules you don't need (see comment). - Then run: - - qmake eql5.pro - make - sudo make install (Unix only) - - This will build the executable, the shared library and the modules. - - If you ran "make install", you'll find the installed files here: - - /usr/local/bin/ - /usr/local/lib/ - /usr/local/include/eql5/ - -3) cd .. - - [Linux] - N.B. skip this if you did "sudo make install" - - You need to create links to EQL, something like (note the "5"): - cd /usr/lib - sudo ln -s ~/eql5/libeql5.so.1 libeql5.so.1 - cd /usr/bin - sudo ln -s ~/eql5/eql5 eql5 - - [OSX] - N.B. skip this if you did "sudo make install" - - You need to create links to EQL, something like (note the "5"): - cd /usr/local/lib - sudo ln -s ~/eql5/libeql5.1.dylib libeql5.1.dylib - cd /usr/local/bin - sudo ln -s ~/eql5/eql5.app/Contents/MacOS/eql5 eql5 - - [Windows] - Add your EQL directory to the Path environment variable, see: - - - - -RUN -=== - -You can run a simple interactive REPL UI doing: - eql5 -qgui - -To run a Lisp file without top-level, do: - eql5 examples/2-clock - -(If you don't see the application window, it might be in the background. -Use your taskbar to show it.) - -If you start the EQL executable without arguments, it will start the usual ECL -top-level (without processing Qt events). - -To _not_ load ~/.eclrc on startup, do: - eql5 -norc - -To quit the tool, do: - (eql:qquit) or - (eql:qq) - -In order to run (sort of) a top-level processing Qt events, do: - eql5 -qtpl - - Note: If you want to use "ecl-readline" together with "-qtpl", just compile - "lib/ecl-readline.lisp" (which depends on the "readline" C library). - It will then be loaded automatically on startup: - - cd ~/eql5/lib - ecl -compile ecl-readline.lisp - - N.B: Using readline, you will often need to "reset" (command) your - console/shell after EQL finished working, especially during - development time or other exits than "(eql:qquit)". - - - -QT MODULES (help, multimedia, network, quick, sql, svg, webengine, webkit) -========== - -N.B. skip this if you already built from 'eql5.pro' (see above) - - To build an EQL module (corresponding to a Qt module), do the following in - src/: - - qmake module_.pro (e.g. qmake module_network.pro) - make - sudo make install (Unix only) - - [Linux,OSX] - (N.B. skip this if you did "sudo make install") - You need to create links to the modules, see EQL library above. - -In Lisp, use function QREQUIRE to load a module: - - (qrequire :network) - - - -TIPS -==== - -You might want to put this in your ~/.eclrc file: - - #+eql - (setf eql:*qtpl* t ; same as -qtpl - eql:*break-on-errors* t) - -It is HIGHLY RECOMMENDED to integrate the wrapper functions, see -README-3-OPTIONAL. -This will make all Qt functions real Lisp functions, which also means symbol -tab-completion, both in Emacs/Slime and with ecl-readline. - -Please see also example "examples/X-extras/CLOS-encapsulation.lisp" for -encapsulation of Qt classes in Lisp classes or structs (that is, Lisp classes -that behave like a Qt class if passed to Qt functions). - - - -NOTES -===== - -For additional information see doc/index.html. - - - -LICENSE -======= - -MIT - -for MAKE-QIMAGE (contributed by Mark Cox), please see LICENSE-MAKE-QIMAGE.txt - - - -DISCLAIMER -========== - -Clicking around on "gitlab.com" will eventually bring to your attention a chart -with the "used languages". - -I just wanted to clearify that 0.0000000% of "NewLisp" (whatever that means) is -used in this project (a simple and obvious mis-identification). diff --git a/README-2-REBUILD.md b/README-2-REBUILD.md new file mode 100644 index 0000000..89c1a52 --- /dev/null +++ b/README-2-REBUILD.md @@ -0,0 +1,53 @@ + +### Rebuild steps + +(on every upgrade of: ECL, Qt5, EQL5) + +``` + $ cd src + $ rm -fr tmp # Windows: rmdir tmp /s /q + $ ecl -shell make.lisp +``` + +``` + $ qmake eql5.pro + $ make # MSVC: nmake + $ sudo make install # Unix only +``` + +Optional, but recommended (integrate **wrapper functions**): + +``` + $ eql5 make-wrappers.lisp +``` + +``` + $ touch tmp/eql.o # Windows: del tmp/eql.obj +``` + +``` + $ qmake eql_lib.pro + $ make # MSVC: nmake + $ sudo make install # Unix only +``` + + +### Important notes + +*C++* + +You always need to rebuild from any `*.pro` file after upgrading EQL5. + +The simplest way to clean everything is to remove the whole `tmp/` directory in +the respective build directory, since the `Makefile` generated by Qt not always +works correctly with `make clean` (e.g. on Windows). + +*Lisp* + +It's also recommended to recompile any compiled EQL code (because of the tight +ECL/C++ integration). + + +### Tip + +If you're on Linux, see `src/rebuild` (needs password for 'make install`). diff --git a/README-2-REBUILD.txt b/README-2-REBUILD.txt deleted file mode 100644 index 16a1bb4..0000000 --- a/README-2-REBUILD.txt +++ /dev/null @@ -1,47 +0,0 @@ -REBUILD STEPS (on every upgrade of: ECL, Qt, EQL) -============= - -0) cd src - -1) remove directory tmp/ - -2) ecl -shell make.lisp - -3) qmake eql5.pro - make (MSVC: nmake) - sudo make install (Unix only) - -Optionally (integrate wrapper functions): - -4) eql5 make-wrappers.lisp - -5) re-link EQL library: - - touch tmp/eql.o (or delete "tmp/eql.o*") - qmake eql_lib.pro - make (MSVC: nmake) - sudo make install (Unix only) - - -IMPORTANT NOTES -=============== - -C++: - -You always need to rebuild from any "*.pro" file (EQL modules, Qt_EQL...) after -upgrading EQL. - -The simplest way to clean everything is to remove the whole "tmp/" directory in -the respective build directory, since the Makefile generated by Qt not always -works correctly with "make clean" (e.g. on Windows). - -Lisp: - -It's also recommended to recompile any compiled EQL code (because of the tight -ECL/C++ integration). - - -TIP -=== - -If you're on Linux, see "src/rebuild" (needs password for make install). diff --git a/README-3-OPTIONAL.md b/README-3-OPTIONAL.md new file mode 100644 index 0000000..c2af959 --- /dev/null +++ b/README-3-OPTIONAL.md @@ -0,0 +1,55 @@ + +### Wrapper functions + +(for manual loading, see `src/lisp/all-wrappers.lisp`) + +Examples: + +``` + (|show| widget) + + (|toString| (|currentTime.QTime|)) ; static function +``` + + +### Integrate them permanently + +Build EQL5 as usual, then run + +``` + $ eql5 make-wrappers.lisp +``` + +``` + $ touch tmp/eql.o # Windows: del tmp/eql.obj +``` + +``` + $ qmake eql_lib.pro + $ make # MSVC: nmake + $ sudo make install # Unix only +``` + +Note: The resulting shared library should be stripped (automatically done by +`make install`); this will reduce its size considerably. + +-- + +The convenience macro `x:do-with` has been adapted to work with the wrappers: + +``` + (x:do-with item + (|setTextAlignment| 0 |Qt.AlignRight|) + (|setText| 0 "123")) +``` + +-- + +Normally not needed, but if you want to generate the wrappers for your +Qt version (much different from Qt 5.5) do: + +``` + $ cd src/lisp + $ eql5 define-all-wrappers.lisp +``` + diff --git a/README-3-OPTIONAL.txt b/README-3-OPTIONAL.txt deleted file mode 100644 index ed9ca86..0000000 --- a/README-3-OPTIONAL.txt +++ /dev/null @@ -1,51 +0,0 @@ -Wrapper functions -================= - -If you want to use wrapper functions for all Qt functions, see: - - "src/lisp/all-wrappers.lisp" - -Examples: - - (|show| widget) - - (|toString| (|currentTime.QTime|)) ; static function - - -Notes -===== - -If you want to add the wrappers permanently, build EQL as usual, then run - - eql5 make-wrappers.lisp - -Re-link EQL doing something like: - - touch tmp/eql.o* (or delete "tmp/eql.o*") - qmake eql_lib.pro - make - sudo make install (Unix only) - -Note: The resulting shared library should be stripped (automatically done by -"make install"); this will reduce its size considerably. - ---- - -The convenience macro X:DO-WITH has been adapted to work with the wrappers: - - (x:do-with item - (|setTextAlignment| 0 |Qt.AlignRight|) - (|setText| 0 "123")) - ---- - -Normally not needed, but if you want to generate the wrappers for your -Qt version (much different from Qt 5.5) do: - - cd src/lisp - eql5 define-all-wrappers.lisp - ---- - -See also note in Sokoban example (no more casts needed). - diff --git a/README-4-KNOWN-ISSUES.md b/README-4-KNOWN-ISSUES.md new file mode 100644 index 0000000..0f2fbb5 --- /dev/null +++ b/README-4-KNOWN-ISSUES.md @@ -0,0 +1,17 @@ + +*Linux* + +After using `QFileDialog`, you may experience an infinite error message loop +when quitting EQL5. +The `SIGSEGV` happens in `QIcon::~QIcon()`, and is therefore neither the fault +of ECL nor EQL5. +(It seems to be related to Gtk/Themes.) + +A drastic measure against this annoying behaviour is calling `abort()` instead +of `exit()` by using: + +``` + (eql:qquit -1) ; negative exit status +``` + +which would be `:abort` or `:qa` directly on the top-level. diff --git a/README-4-KNOWN-ISSUES.txt b/README-4-KNOWN-ISSUES.txt deleted file mode 100644 index acaaea2..0000000 --- a/README-4-KNOWN-ISSUES.txt +++ /dev/null @@ -1,11 +0,0 @@ -[Linux] - -After using QFileDialog, you may experience an infinite error message loop when quitting EQL. -The SIGSEGV happens in QIcon::~QIcon(), and is therefore neither the fault of ECL nor EQL. -(It seems to be related to Gtk/Themes.) - -A drastic measure against this annoying behaviour is calling "abort()" instead of "exit()" by using: - - (eql:qquit -1) ; negative exit status - -which would be :abort or :qa directly on the top-level.