From a8a6a6e29099b05afe9863e34a298fe117f1d24e Mon Sep 17 00:00:00 2001 From: David Botton Date: Thu, 11 Jul 2024 15:37:21 -0400 Subject: [PATCH] release docs --- LINUX.md | 4 ++- MACOS.md | 2 ++ NATIVE.md | 93 +++++++----------------------------------------------- README.md | 86 ++++++++++++++++++++++---------------------------- WINDOWS.md | 3 +- 5 files changed, 57 insertions(+), 131 deletions(-) diff --git a/LINUX.md b/LINUX.md index 1c4fc49f..3c98357e 100644 --- a/LINUX.md +++ b/LINUX.md @@ -1,6 +1,8 @@ ## Installing Common Lisp + CLOG Builder on Linux (all platforms) -(For emacs based Linux install - https://lisp-lang.org/learn/getting-started/) +For emacs based Linux install - https://lisp-lang.org/learn/getting-started/) + +Also see another alternative [Install and Using OCICL on all platforms](OCICL.md) 1. Install sbcl, sqlite and openssh (modify for your OS) diff --git a/MACOS.md b/MACOS.md index d4eba977..4a8d5341 100644 --- a/MACOS.md +++ b/MACOS.md @@ -3,6 +3,8 @@ (If you do not want emacs skip steps 1,2,6, and 7 and just use the CLOG Builder) +also see [Install and Using OCICL on all platforms](OCICL.md) + 1. Install Emacs for Mac OS from - https://emacsformacosx.com/ 2. [optional] Add Emacs to your system's path by creating a diff --git a/NATIVE.md b/NATIVE.md index e8f774f3..6f9232d2 100644 --- a/NATIVE.md +++ b/NATIVE.md @@ -1,31 +1,34 @@ # Creating Native Applications with CLOG -## The Simple solution: +## The Simple solutions: -Common to all solutions is compiling you CLOG application to an executable. +1. Common to all solutions is compiling you CLOG application to an executable. See demos/make-snake and the source of the 01-demo.lisp file. make-snake produces a native app that launches a browser. When snake game exist the executable quits. -or better yet use CLOGFRAME - see clogframe/README.md and the built in +2. You can use CLOGFrame - see clogframe/README.md and the built in browser control on your OS. -## More advanced solutions: +## Other solutions: -1. Open app using chrome in app mode (not exactly native but looks it) +1. Use the Ceramic project that uses Electron (win,linux,mac) -2. Use MacGap on Mac +2. Chrome app mode -3. Native app using (ql:quickload :ceramic) (works well for Windows and Linux) +3. Use MacGap on Mac 4. Native iOS and Android using Cordova and ECL -5. Webview.h ## 1 Open app using chrome in app mode +Sample project https://github.com/rabbibotton/elect + +## 2 Open app using chrome in app mode + To open a chrome window in app mode use -app="URL" for example to start the builder as an app: @@ -41,7 +44,7 @@ On Windows chrome --new-window --app="http://127.0.0.1:8080/builder" -## 2 Use MacGap and XCode +## 3 Use MacGap and XCode https://github.com/MacGapProject/MacGap2 @@ -52,79 +55,7 @@ open MacGap2/MG.xcodeproj/ In public/index.html in Xcode you use: MacGap.launch(appName) to launch your app. Then connect to it on the port you have chosen. -## 3 Using Ceramic Mac/Windows/Linux - -The documentation for ceramic is at: -http://ceramic.github.io/ - -Complete project at - https://github.com/rabbibotton/elect - -1. (ql:quickload :ceramic) -2. (ceramic:setup) - -Now that ceramic is installed. We create a new project using CLOG Builder: - -1. (ql:quickload :clog/tools) -2. (clog-tools:clog-builder) - -In CLOG Builder: - -1. Choose Builder->New Application Template -2. Choose a template for your project - I will use CLOG-GUI -3. Give the new project a name - I am using elect as the project name -4. Choose the default directory ~/common-lisp or another that works for you - -In the REPL let's load the new project: - -1. Let's open ~/common-lisp/elect/elect.asd -2. Add to depends-on #:ceramic -3. Let's open ~/common-lisp/elect/elect.lisp -4. Replace start-app with: - -``` -(defvar *window* nil) - -(defun start-app (&key (port 8080)) - (ceramic:start) - (initialize 'on-new-window - :port port - :static-root (ceramic:resource-directory 'www)) - (setf *window* - (ceramic:make-window :url (format nil "http://127.0.0.1:~D/" port))) - (ceramic:show *window*)) - -(ceramic:define-resources :elect () - (www #p"www/")) - -(ceramic:define-entry-point :elect () - (start-app)) -``` - -5. We need to add to the botton of on-new-window code to shutdown app. - -``` - (clog:run body) ; wait while body is running - (ceramic:quit) ; quit ceramic/electron - (clog:shutdown) ; shutdown clog -``` - -6. I suggest starting from scratch at this point: M-x slime-restart-inferior-lisp -7. (ql:quickload :elect) -8. (elect:start-app) - -That should start up a native application with your CLOG app - -To package you applicaton use: - -1. (ceramic:bundle :elect) - ## 4 Native iOS and Android using Cordova and ECL https://cordova.apache.org/ - -## 5 Webview.h - -https://github.com/webview/webview - -See clogframe for working external example \ No newline at end of file diff --git a/README.md b/README.md index 8fd08837..d8ad2ef0 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ embedded in a native application.) - [CLOG - Reference Manual](https://rabbibotton.github.io/clog/clog-manual.html) -STATUS: CLOG and CLOG Builder 2.2 released. CLOG API Stable 4 years +STATUS: CLOG and CLOG Builder 2.3 released. CLOG API Stable 4 years The CLOG Builder is in 100% portable Common Lisp using the CLOG Framework. @@ -27,13 +27,15 @@ CLOG tech was invented (first in Ada) and has been running in commercial production code and productss since 2013 and in Common Lisp since 2022. CLOG is used in commerical products, websites, and other opensource projects. -CLOG is being actively extended, however the core API is stable and proven, -the CLOG Builder is rich in features and is a full featured IDE for Common Lisp -and web development and includes a GUI Builder for the CLOG Framework. +CLOG is being actively extended, the core API is stable and proven, +the CLOG Builder is rich in features and is a full featured general purpose +IDE for Common Lisp and web development (including support for working on +JavaScript, HTML and more) and includes a GUI Builder for the CLOG Framework. Check the github discussion boards for the latest on the project and support. Consider sponsoring work on CLOG at https://github.com/sponsors/rabbibotton +it really does help! Some potential applications for CLOG: @@ -58,20 +60,32 @@ CLOG is developed with ECL, CCL and SBCL, it is tested fairly regulary on Linux, Windows, Android, Rasperry Pi, and Mac. It is also know to work with the commercial Common Lisps as well. -To install Common Lisp and CLOG: +CLOG works with QuickLisp and with OCICL distribution for builds. + +To install Common Lisp with QuikLisp: * [Install Common-Lisp for MacOS](MACOS.md) * [Install Common-Lisp for Linux](LINUX.md) * [Install Common-Lisp For Android (Termux)](ANDROID-TERMUX.md) * [Install Common-Lisp for Win64](WINDOWS.md) -For **Windows** users there is an easy install for full CL and CLOG - -https://github.com/rabbibotton/clog-win64-ez/releases -Unzip, double click setup.bat and then drag the resulting builder.exe to your -application bar or double click. Update regularly by running update.bat -If you change directories you need to run make.bat or update.bat -You can also run frame.bat to produce a version of builder that does not use -the browser. +For more advanced users: + +* [Install and Using OCICL on all platforms](OCICL.md) + +For those new to Common Lisp or just want to quickly try CLOG use ther +simple _EZ_ standalone versions: + +* https://github.com/rabbibotton/clog-win64-ez/releases +* https://github.com/rabbibotton/clog-linux-ez +* https://github.com/rabbibotton/clog-linux-arm-ez +* https://github.com/rabbibotton/clog-mac-ez + +Unzip, double click setup.bat or ./setup +Run builder.exe or ./builder +Update (almost daily :) use update.bat or ./update + +As QuickLisp most frequently used - here are instructions: CLOG v1 is in QuickLisp (ql:quickload :clog), therefore one should add the UltraLisp distribution to use CLOG v2 (alternatively use git) @@ -91,43 +105,23 @@ You still need to update often the UltraLisp and QuickLisp distros with: If using the CLOG Builder Options -> Update CLOG Builder will do this for you. -To get started load CLOG and then can load and run the builder: - -``` -(ql:quickload :clog/tools) -(clog-tools:clog-builder) - -``` - -You can also just run from the command line run-builder or run-builder.bat +Q U I C K S T A R T +===================== -To use the git versions CLOG, place git clone into ~/common-lisp or -a findable source directory, i.e. -[ ``(push #P"path/to/dir/of/projects" ql:*local-project-directories*)`` ] -For git (you also need the clog builder plugins clog-ace and clog-terminal -for the builder or use the UltraLisp versions): +1) To get started load CLOG and then can load and run the builder: ``` -cd ~/common-lisp -git clone https://github.com/rabbibotton/clog.git -git clone https://github.com/rabbibotton/clog-ace.git -git clone https://github.com/rabbibotton/clog-terminal.git +sbcl --eval "(ql:quickload :clog/tools)" --eval "(clog-tools:clog-builder)" ``` +or if using OCICL see [Install and Using OCICL on all platforms](OCICL.md) +or if using emacs M-x slime then (ql:quickload :clog/tools)(clog-tools:clog-builder) -Update git clones with: - -``` -git pull -``` - -1. Start emacs then M-x slime (or just run sbcl at the command line or use the - CLOG Buider REPL Tools -> CLOG Builder Repl) -2. In the REPL, run: +2) In a REPL in the builder Tools -> CLOG Builder REPL +(can _also_ do all in the slime/sly REPL in emacs) ``` -CL-USER> (ql:quickload :clog) ; if not already loaded CL-USER> (clog:run-tutorial 1) ``` @@ -146,17 +140,13 @@ To see where the source, tutorial and demo files are: CL-USER> (clog:clog-install-dir) ``` -You can the run the demos with: +Also in CLOG Builder use HELP -> Tutorials Dir -``` -CL-USER> (clog:run-demo 1) -``` -The CLOG Builder tool can be run with: +You can the run the demos with: ``` -CL-USER> (ql:quickload :clog/tools) -CL-USER> (clog-tools:clog-builder) +CL-USER> (clog:run-demo 1) ``` You can also open a "clog-repl" browser window to play @@ -172,7 +162,7 @@ CLOG-USER> (create-div *body* :content "Hello World!") The clog-repl URL is http://127.0.0.1:8080/repl ``*body*`` will always refer to the last access of that URL. -To open a browser with the CLOG manual (or in the builder it is under Help): +To open the CLOG manual (or in the builder it is under Help): ``` CL-USER> (clog:open-manual) diff --git a/WINDOWS.md b/WINDOWS.md index f0973933..5fcbe932 100644 --- a/WINDOWS.md +++ b/WINDOWS.md @@ -3,6 +3,8 @@ (For a simple "one step" non-emacs install see: https://github.com/rabbibotton/clog-win64-ez/releases) +also see [Install and Using OCICL on all platforms](OCICL.md) + 1. Download and install rho-emacs: https://gchristensen.github.io/rho-emacs/ @@ -90,7 +92,6 @@ sbcl --eval '(ql:quickload :clog/tools)' --eval '(clog-tools:clog-builder)' Run Slime - M-x slime - NOTES for Windows: I have a zip with the needed DLLs should it come up - https://rabbibotton.github.io/clog/clogframe.zip