diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 5214a41b5..f18de9ba8 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -21,13 +21,10 @@ jobs: os: - macos-latest - ubuntu-latest - - windows-latest + # The Server 8 / modern ppx stack (ocsigen-ppx-rpc needs ppxlib >= 0.37, + # pulled together with ppx_sexp_conv -> ppxlib_jane) requires OCaml >= 5.3. ocaml-compiler: - - "4.14" - - "5.2" - include: - - os: ubuntu-latest - ocaml-compiler: "4.12" + - "5" runs-on: ${{ matrix.os }} @@ -46,9 +43,22 @@ jobs: ocaml-compiler: ${{ matrix.ocaml-compiler }} opam-pin: false + # wasm_of_ocaml (pulled in via eliom) needs binaryen's wasm-merge. + - name: Set-up Binaryen + uses: Aandreba/setup-binaryen@v1.0.0 + with: + token: ${{ github.token }} + + # Pin the Ocsigen Server 8 development branches until 8.0 is released + # (the default branches of these repos are still the Server 7 line). - run: | - opam pin add -n eliom https://github.com/ocsigen/eliom.git - opam pin add -n ocsigen-toolkit https://github.com/ocsigen/ocsigen-toolkit.git + opam pin -yn git+https://github.com/ocsigen/ocsigenserver#master + opam pin -yn git+https://github.com/ocsigen/ocsipersist#master + opam pin -yn git+https://github.com/ocsigen/eliom#deriving + opam pin -yn git+https://github.com/ocsigen/ocsigen-toolkit#modernize + opam pin -yn git+https://github.com/ocsigen/ocsigen-dune-rules#modernize + opam pin -yn git+https://github.com/ocsigen/ocsigen-ppx-rpc#modernize + opam pin -yn git+https://github.com/ocsigen/ocsigen-i18n#modernize - run: opam pin add ocsigen-start.7.0.0 . --no-action @@ -56,7 +66,14 @@ jobs: - run: mkdir -p template - - run: opam exec -- eliom-distillery -name template -template os.pgocaml + - run: opam exec -- eliom-distillery -name template -template os + + # Make the generated project its own dune root. It lives inside the + # ocsigen-start checkout, which ships a dune-project; without this, dune + # would take ocsigen-start as the root and treat the project as a nested + # subdirectory, which breaks Eliom's client/server value linking + # ("Inferred type of client value not found. You need to regenerate ..."). + - run: echo '(lang dune 3.0)' > template/dune-workspace - run: opam install -y . working-directory: template diff --git a/.gitignore b/.gitignore index 649e8d638..32d82fed8 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ local/ doc/client doc/server .*.sw* +doc/manual/menu.wiki diff --git a/.ocamlformat b/.ocamlformat index a84459a47..5fb3439a0 100644 --- a/.ocamlformat +++ b/.ocamlformat @@ -1,4 +1,4 @@ -version=0.28.1 +version=0.29.0 parse-docstrings = false wrap-comments = false break-cases = fit diff --git a/CHANGES b/CHANGES index f6090651b..56fb5d189 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,36 @@ +===== 9.0.0~dev ===== +* Module namespace modernization +** Public modules are now accessed as Os.Session, Os.User, Os.Tips, + Os.Mail, Os.Notif, ... instead of the legacy flat Os_xxx prefix. + Implemented with (include_subdirs qualified) + (wrapped false) + in dune. +** New ocsigen-start-compat opam package: provides the legacy + Os_xxx module names as include-aliases of the new Os.Xxx + modules, to ease migration of existing code. +* PROJECT_NAME_icons.eliom in the distillery template is now + parameterised on Eliom.Content.Html.T (the shared signature + exposed by Eliom 13) instead of an ad-hoc ICON_HTML signature. +* Distillery template +** Renamed from os.pgocaml to os. +** Source directory renamed back to template.distillery/ (the + convention used by ocsigen-start's previous Makefile-based + build), and now installed via dune + (install (section lib_root) (files (glob_files_rec + (template.distillery/* with_prefix eliom/templates/os)))) + so the template lands at lib/eliom/templates/os/, where + eliom-distillery picks it up at the standard location (Eliom + 13 dropped the per-package eliom-templates/ auto-discovery). +* Migrated to the new Eliom 13 module names (Eliom.Service, + Eliom.Content, Eliom.Common, ...) and to the wrapped + ocsigenserver module names (Ocsigen.Server, Ocsigen.Extensions, + Ocsigen.Config, Ocsigen_base.Lib, ...). +* Build system uses ocsigen-dune-rules (gen sub-command). +* Os.Email: the default email-sending function now pipes an RFC-2822 + message to the configured mailer ("sendmail" by default) via + Lwt_process, instead of printing to stdout. If the mailer is not on + PATH, the email is logged to stderr so the application stays usable + out of the box. The now-unused [Invalid_mailer] exception is removed. + ===== 7.1.0 (2024-11) ===== * Compatibility with WASM diff --git a/doc/client.indexdoc b/doc/client.indexdoc new file mode 100644 index 000000000..9cd4542d0 --- /dev/null +++ b/doc/client.indexdoc @@ -0,0 +1,57 @@ +{1 Ocsigen Start client API} + +{2 User management} + +{!modules: +User +User_view +User_proxy +Current_user +Session +Connect_phone +} + +{2 Persistence} + +{!modules: +Types +Email +} + +{2 Notifications} + +{!modules: +Notif +Msg +Fcm_notif +} + +{2 Web pages and services} + +{!modules: +Page +Services +Handlers +Icons +Tips +Uploader +Request_cache +} + +{2 Real-time} + +{!modules: +Comet +} + +{2 Utilities} + +{!modules: +Lib +Date +Platform +} + +{2 Indexes} + +{!indexlist} diff --git a/doc/dune b/doc/dune index b2c4e3255..04835aee6 100644 --- a/doc/dune +++ b/doc/dune @@ -1,5 +1,6 @@ ; Ocsigen Start manual pages (odoc .mld), compiled in place with the API by ; `dune build @doc` and installed with the package, so they appear on ocaml.org ; and resolve {{!page-X}} / {!Module} references against the API. + (documentation (package ocsigen-start)) diff --git a/doc/index.mld b/doc/index.mld index 61446453e..207a5b92e 100644 --- a/doc/index.mld +++ b/doc/index.mld @@ -6,19 +6,234 @@ client-server web and mobile applications with {{!/eliom/page-index}Eliom} and notifications, a database schema and many code examples, so you can focus on your own features from day one. +Use it to learn Ocsigen or to quickly create your own Minimum Viable +Product. The application is cross-platform: it works as a Web app or as +a mobile app for iOS or Android (via {{:https://cordova.apache.org/}Cordova}). + Ocsigen Start is part of the {{:https://ocsigen.org}Ocsigen project}. -{1 Documentation} +{1 Demo} + +If you want to test the demo application before installing Ocsigen Start, +{b a live version is running {{:https://ocsigen.org/ocsigen-start/demo/}here}}. + +You can also download the mobile app +{{:https://play.google.com/store/apps/details?id=com.osdemo.mobile}on Google Play store} (for Android) +or download the +{{:files/osdemo.apk}APK for Android} +or the +{{:files/osdemo-ios.tgz}iOS version} (to be installed using XCode). + +{%wodoc:div class="screenshots"%} +{{:files/screenshots/start1.png} +{%wodoc:img src="files/screenshots/start1.png" alt="Ocsigen Start"%}} +{{:files/screenshots/start2.png} +{%wodoc:img src="files/screenshots/start2.png" alt="Ocsigen Start"%}} +{%wodoc:end%} + +{%wodoc:div class="screenshots"%} +{{:files/screenshots/start-mobile-1.png} +{%wodoc:img src="files/screenshots/start-mobile-1.png" alt="Ocsigen Start"%}} +{{:files/screenshots/start-mobile-2.png} +{%wodoc:img src="files/screenshots/start-mobile-2.png" alt="Ocsigen Start"%}} +{{:files/screenshots/start-mobile-4.png} +{%wodoc:img src="files/screenshots/start-mobile-4.png" alt="Ocsigen Start"%}} +{%wodoc:end%} + + + +Ocsigen Start is composed by two main parts: + +- The generated code which gives a default behaviour to your application. Adapt it to your needs and remove the parts you don't need. Feel free to redistribute it as you wish.{%html:
%} +It includes a demo of many features from Eliom, Js_of_ocaml, Tyxml, Ocsigen Toolkit. Use it to learn quickly the main principles of multi-tier programming. + +- A library with: +- User management: authentication, registration of new users with activation links sent by email, recover lost password, page to update settings, etc. +- Tips for new users +- Push notifications to send information to other users +- ... + +{%wodoc:div class="screenshots"%} +{{:files/screenshots/start3.png} +{%wodoc:img src="files/screenshots/start3.png" alt="Ocsigen Start"%}} +{{:files/screenshots/start4.png} +{%wodoc:img src="files/screenshots/start4.png" alt="Ocsigen Start"%}} +{{:files/screenshots/start5.png} +{%wodoc:img src="files/screenshots/start5.png" alt="Ocsigen Start"%}} +{{:files/screenshots/start6.png} +{%wodoc:img src="files/screenshots/start6.png" alt="Ocsigen Start"%}} +{%wodoc:end%} + +{%wodoc:div class="screenshots"%} +{{:files/screenshots/start-mobile-3.png} +{%wodoc:img src="files/screenshots/start-mobile-3.png" alt="Ocsigen Start"%}} +{{:files/screenshots/start-mobile-6.png} +{%wodoc:img src="files/screenshots/start-mobile-6.png" alt="Ocsigen Start"%}} +{{:files/screenshots/start-mobile-7.png} +{%wodoc:img src="files/screenshots/start-mobile-7.png" alt="Ocsigen Start"%}} +{{:files/screenshots/start-mobile-8.png} +{%wodoc:img src="files/screenshots/start-mobile-8.png" alt="Ocsigen Start"%}} +{%wodoc:end%} + + +{1 Getting started} + +Read {{:https://ocsigen.org/tuto/start.html}this page} to learn how to build your first Ocsigen Start app in 5 minutes. + +{1 Implementation overview} + +{2 Template} + +The library portion of Ocsigen Start contains core functionality that +is common across Ocsigen Start applications, while the template can be +customized for the specific application at hand. + +The template additionally contains a demonstration of relevant +{{:https://github.com/ocsigen/ocsigen-toolkit}Ocsigen Toolkit} +widgets. The demo portion can easily be removed. + +{2 Database} + +For implementing users, a database is needed. Specifically, we use +{{:https://www.postgresql.org/}PostgreSQL} via the +{{:http://pgocaml.forge.ocamlcore.org/}PGOCaml} library. The template +and the library make common assumptions about the database schema. The +database thus needs to be instantiated in a certain way; this is +automatically done by appropriate targets in the template's build +system. + +The same database can used for the specific needs of the application +at hand. For that, new tables can be added. The original ones should +remain in place for Ocsigen Start to work correctly. + +{2 Internationalization (i18n)} + +The template is available in multiple languages (English and French) using +{{:https://github.com/besport/ocsigen-i18n}ocsigen-i18n}. All translations used +in the template are defined in the file [assets/PROJECT_NAME_i18n.tsv]. The +Makefile rule [i18n-udpate] generates the i18n module. You need to use it +every time the TSV file is updated. + +See [Makefile.i18n] for rules about i18n and [Makefile.options] to +personalize the internalization of your application (for example add new +languages, change default language, change TSV filename). + +{2 Managing e-mails} + +The template application keeps track of users' e-mails and implements +e-mail validation. For that, [sendmail] (or another mail transfer +agent compatible with it) needs to be installed on the host. -- {{!page-intro}Introduction} — installation, getting started and an - overview of the modules Ocsigen Start provides. -- The server and client API of every module (use the {e Server API} / - {e Client API} switch to move between the two sides). +{2 Style} + +The application provides a standard style matching contemporary +aesthetics. For this, we use {{:http://sass-lang.com/}SASS}. The style +can be customized by modifying the SASS files that are part of the +template. {1 Installation} -Ocsigen Start is available via OPAM: +Ocsigen Start can be installed via +{{:https://opam.ocaml.org/}OPAM}. The package name is [ocsigen-start]. +The template application can be instantiated via [eliom-distillery]: -{[ -opam install ocsigen-start +{@shell[ +eliom-distillery -name $APP_NAME -template os ]} + +(Replace $APP_NAME by the name of your application). + +For details on launching the application, refer to the template's +{{:https://github.com/ocsigen/ocsigen-start/blob/master/template.distillery/README.md}README}. + +{1 Library overview} + +We provide a tour of the Ocsigen Start library. All modules have +server- and client-side versions. (In the API documentation, there are +links near the top of each module page for selecting the side.) + +The template uses all these modules, and can thus act as a good +starting guide. Look around! + +{2 User interface} + +Various modules for producing icons, messages, custom pages, tips, +connection forms, etc. + +- {!Os.Icons}: + manage CSS icons. +- {!Os.Msg}: + write messages in the browser console. +- {!Os.Page}: + utilities for building HTML pages that follow the standard Ocsigen + Start layout. +- {!Os.Tips}: + display tips to the user. +- {!Os.User_view}: + functions for creating password forms and other common UI elements + appearing in applications and for managing the user connection box. +- {!Os.Uploader}: + ImageMagick-based tools for manipulating avatars. + +{2 Users and groups} + +- {!Os.User}, + {!Os.Current_user}, + {!Os.Group}: + manage users and groups thereof. + +- {!Os.Db}: + directly access the database. In many cases, it is a better idea to + use higher-level modules (e.g., + {!Os.User}). + +- {!Os.Types}: + core types shared by {!Os.Db} + and the higher-level modules. + +{2 Communication} + +- {!Os.Notif}: + send notifications to connected users. + +- {!Os.Email}: + send e-mails. + +- {!Os.Fcm_notif}: + send push notifications to mobile devices. + +- {!Os.Comet}: + manage the bi-directional communication channel between client and + server. This is a low-level module that you probably don't need. + +{2 Services, handlers, sessions} + +- {!Os.Services}: + Eliom services pre-defined by Ocsigen Start. These produce the + default user interface of the template. + See {{!/eliom/page-"server-services"}the Eliom manual page on services} for + a general introduction to Eliom services. + +- {!Os.Handlers}: + The handlers (functions) that implement the services in + {!Os.Services}. + {{!/eliom/page-"server-outputs"}The Eliom manual page on service handlers} + explains how to implement handlers. + +- {!Os.Session}: + manage user sessions, e.g., execute actions when users connect or + disconnect. + +{2 Other utilities} + +- {!Os.Date}: + utilities for manipulating date and time values. + +- {!Os.Platform}: + obtain information about the platform we are on (Android, iOS, ...). + +- {!Os.Request_cache}, + {!Os.User_proxy}: + different forms of caching data. + +- A {e ppx} syntax extension to implement RPC. diff --git a/doc/intro.mld b/doc/intro.mld deleted file mode 100644 index efa11ab28..000000000 --- a/doc/intro.mld +++ /dev/null @@ -1,241 +0,0 @@ - - -{0 Introduction} - -Ocsigen Start is an application template written with Eliom, Js_of_ocaml, -Ocsigen Toolkit, etc. -It contains many standard features like user management, notifications, -and many code examples. - -Use it to learn Ocsigen or to quickly create your own Minimum Viable Product. -It is probably the fastest way to get started with Ocsigen. - -The application is cross-platform: it works as a Web app or as a mobile app -for iOS or Android (via {{:https://cordova.apache.org/}Cordova}).. - - -{1 Demo} - -If you want to test the demo application before installing Ocsigen Start, -{b a live version is running {{:https://ocsigen.org/ocsigen-start/demo/}here}}. - -You can also download the mobile app -{{:https://play.google.com/store/apps/details?id=com.osdemo.mobile}on Google Play store} (for Android) -or download the -{{:files/osdemo.apk}APK for Android} -or the -{{:files/osdemo-ios.tgz}iOS version} (to be installed using XCode). - -{%wodoc:div class="screenshots"%} -{{:files/screenshots/start1.png} -{%wodoc:img src="files/screenshots/start1.png" alt="Ocsigen Start"%}} -{{:files/screenshots/start2.png} -{%wodoc:img src="files/screenshots/start2.png" alt="Ocsigen Start"%}} -{%wodoc:end%} - -{%wodoc:div class="screenshots"%} -{{:files/screenshots/start-mobile-1.png} -{%wodoc:img src="files/screenshots/start-mobile-1.png" alt="Ocsigen Start"%}} -{{:files/screenshots/start-mobile-2.png} -{%wodoc:img src="files/screenshots/start-mobile-2.png" alt="Ocsigen Start"%}} -{{:files/screenshots/start-mobile-4.png} -{%wodoc:img src="files/screenshots/start-mobile-4.png" alt="Ocsigen Start"%}} -{%wodoc:end%} - - - -Ocsigen Start is composed by two main parts: - -- The generated code which gives a default behaviour to your application. Adapt it to your needs and remove the parts you don't need. Feel free to redistribute it as you wish.{%html:
%} -It includes a demo of many features from Eliom, Js_of_ocaml, Tyxml, Ocsigen Toolkit. Use it to learn quickly the main principles of multi-tier programming. - -- A library with: -- User management: authentication, registration of new users with activation links sent by email, recover lost password, page to update settings, etc. -- Tips for new users -- Push notifications to send information to other users -- ... - -{%wodoc:div class="screenshots"%} -{{:files/screenshots/start3.png} -{%wodoc:img src="files/screenshots/start3.png" alt="Ocsigen Start"%}} -{{:files/screenshots/start4.png} -{%wodoc:img src="files/screenshots/start4.png" alt="Ocsigen Start"%}} -{{:files/screenshots/start5.png} -{%wodoc:img src="files/screenshots/start5.png" alt="Ocsigen Start"%}} -{{:files/screenshots/start6.png} -{%wodoc:img src="files/screenshots/start6.png" alt="Ocsigen Start"%}} -{%wodoc:end%} - -{%wodoc:div class="screenshots"%} -{{:files/screenshots/start-mobile-3.png} -{%wodoc:img src="files/screenshots/start-mobile-3.png" alt="Ocsigen Start"%}} -{{:files/screenshots/start-mobile-6.png} -{%wodoc:img src="files/screenshots/start-mobile-6.png" alt="Ocsigen Start"%}} -{{:files/screenshots/start-mobile-7.png} -{%wodoc:img src="files/screenshots/start-mobile-7.png" alt="Ocsigen Start"%}} -{{:files/screenshots/start-mobile-8.png} -{%wodoc:img src="files/screenshots/start-mobile-8.png" alt="Ocsigen Start"%}} -{%wodoc:end%} - - -{1 Getting started} - -Read {{:https://ocsigen.org/tuto/latest/start.html}this page} to learn how to build your first Ocsigen Start app in 5 minutes. - -{1 Implementation overview} - -{2 Template} - -The library portion of Ocsigen Start contains core functionality that -is common across Ocsigen Start applications, while the template can be -customized for the specific application at hand. - -The template additionally contains a demonstration of relevant -{{:https://github.com/ocsigen/ocsigen-toolkit}Ocsigen Toolkit} -widgets. The demo portion can easily be removed. - -{2 Database} - -For implementing users, a database is needed. Specifically, we use -{{:https://www.postgresql.org/}PostgreSQL} via the -{{:http://pgocaml.forge.ocamlcore.org/}PGOCaml} library. The template -and the library make common assumptions about the database schema. The -database thus needs to be instantiated in a certain way; this is -automatically done by appropriate targets in the template's build -system. - -The same database can used for the specific needs of the application -at hand. For that, new tables can be added. The original ones should -remain in place for Ocsigen Start to work correctly. - -{2 Internationalization (i18n)} - -The template is available in multiple languages (English and French) using -{{:https://github.com/besport/ocsigen-i18n}ocsigen-i18n}. All translations used -in the template are defined in the file [assets/PROJECT_NAME_i18n.tsv]. The -Makefile rule [i18n-udpate] generates the i18n module. You need to use it -every time the TSV file is updated. - -See [Makefile.i18n] for rules about i18n and [Makefile.options] to -personalize the internalization of your application (for example add new -languages, change default language, change TSV filename). - -{2 Managing e-mails} - -The template application keeps track of users' e-mails and implements -e-mail validation. For that, [sendmail] (or another mail transfer -agent compatible with it) needs to be installed on the host. - -{2 Style} - -The application provides a standard style matching contemporary -aesthetics. For this, we use {{:http://sass-lang.com/}SASS}. The style -can be customized by modifying the SASS files that are part of the -template. - -{1 Installation} - -Ocsigen Start can be installed via -{{:https://opam.ocaml.org/}OPAM}. The package name is [ocsigen-start]. -The template application can be instantiated via [eliom-distillery]: - -{@shell[ -eliom-distillery -name $APP_NAME -template os.pgocaml -]} - -(Replace $APP_NAME by the name of your application). - -For details on launching the application, refer to the template's -{{:https://github.com/ocsigen/ocsigen-start/blob/master/template.distillery/README.md}README}. - -{1 Library overview} - -We provide a tour of the Ocsigen Start library. All modules have -server- and client-side versions. (In the API documentation, there are -links near the top of each module page for selecting the side.) - -The template uses all these modules, and can thus act as a good -starting guide. Look around! - -{2 User interface} - -Various modules for producing icons, messages, custom pages, tips, -connection forms, etc. - -- {!Os_icons}: - manage CSS icons. -- {!Os_msg}: - write messages in the browser console. -- {!Os_page}: - utilities for building HTML pages that follow the standard Ocsigen - Start layout. -- {!Os_tips}: - display tips to the user. -- {!Os_user_view}: - functions for creating password forms and other common UI elements - appearing in applications and for managing the user connection box. -- {!Os_uploader}: - ImageMagick-based tools for manipulating avatars. - -{2 Users and groups} - -- {!Os_user}, - {!Os_current_user}, - {!Os_group}: - manage users and groups thereof. - -- {!Os_db}: - directly access the database. In many cases, it is a better idea to - use higher-level modules (e.g., - {!Os_user}). - -- {!Os_types}: - core types shared by {!Os_db} - and the higher-level modules. - -{2 Communication} - -- {!Os_notif}: - send notifications to connected users. - -- {!Os_email}: - send e-mails. - -- {!Os_fcm_notif}: - send push notifications to mobile devices. - -- {!Os_comet}: - manage the bi-directional communication channel between client and - server. This is a low-level module that you probably don't need. - -{2 Services, handlers, sessions} - -- {!Os_services}: - Eliom services pre-defined by Ocsigen Start. These produce the - default user interface of the template. - See {{!/eliom/page-"server-services"}the Eliom manual page on services} for - a general introduction to Eliom services. - -- {!Os_handlers}: - The handlers (functions) that implement the services in - {!Os_services}. - {{!/eliom/page-"server-outputs"}The Eliom manual page on service handlers} - explains how to implement handlers. - -- {!Os_session}: - manage user sessions, e.g., execute actions when users connect or - disconnect. - -{2 Other utilities} - -- {!Os_date}: - utilities for manipulating date and time values. - -- {!Os_platform}: - obtain information about the platform we are on (Android, iOS, ...). - -- {!Os_request_cache}, - {!Os_user_proxy}: - different forms of caching data. - -- A {e ppx} syntax extension to implement RPC. diff --git a/doc/server.indexdoc b/doc/server.indexdoc new file mode 100644 index 000000000..5cb58a89d --- /dev/null +++ b/doc/server.indexdoc @@ -0,0 +1,60 @@ +{1 Ocsigen Start server API} + +{2 User management} + +{!modules: +User +User_view +User_proxy +Current_user +Group +Session +Connect_phone +} + +{2 Persistence} + +{!modules: +Db +Core_db +Types +Email +} + +{2 Notifications} + +{!modules: +Notif +Msg +Fcm_notif +} + +{2 Web pages and services} + +{!modules: +Page +Services +Handlers +Icons +Tips +Uploader +Request_cache +} + +{2 Real-time} + +{!modules: +Comet +} + +{2 Utilities} + +{!modules: +Lib +Date +Platform +} + +{2 Indexes} + +{!indexlist} diff --git a/doc/wodoc b/doc/wodoc index f5d6588f8..9a5328ec1 100644 --- a/doc/wodoc +++ b/doc/wodoc @@ -1,28 +1,21 @@ ;; Declarative wodoc config for the Ocsigen Start documentation (client/server). ;; wodoc build --config doc/wodoc --out /