From 89ed84b9e47d1ba0da4592dde70f06a3158da110 Mon Sep 17 00:00:00 2001 From: Michael Bell Date: Sat, 1 Oct 2022 17:02:27 +0100 Subject: [PATCH] Update docs to reflect recent build and dependency changes --- CHANGELOG.md | 1 + README.md | 14 +++---- docs/nodejs/releasing.md | 86 ---------------------------------------- docs/releasing.md | 8 ++-- docs/windows-deps.md | 85 +++++++++------------------------------ 5 files changed, 30 insertions(+), 164 deletions(-) delete mode 100644 docs/nodejs/releasing.md diff --git a/CHANGELOG.md b/CHANGELOG.md index b81435d7ede..95563748f2c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,7 @@ - FIXED: Fix bug with reading Set values from Lua scripts. [#6285](https://github.com/Project-OSRM/osrm-backend/pull/6285) - FIXED: Bug in bicycle profile that caused exceptions if there is a highway=bicycle in the data. [#6296](https://github.com/Project-OSRM/osrm-backend/pull/6296) - FIXED: Internal refactoring of identifier types used in data facade [#6044](https://github.com/Project-OSRM/osrm-backend/pull/6044) + - CHANGED: Update docs to reflect recent build and dependency changes [#6383](https://github.com/Project-OSRM/osrm-backend/issues/6383) - Build: - ADDED: Build Node bindings on Windows. [#6334](https://github.com/Project-OSRM/osrm-backend/pull/6334) - ADDED: Configure cross-compilation for Apple Silicon. [#6360](https://github.com/Project-OSRM/osrm-backend/pull/6360) diff --git a/README.md b/README.md index 3f06d88525c..5f2fb297d20 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ If you want to use the CH pipeline instead replace `osrm-partition` and `osrm-cu ### Using Docker -We base our Docker images ([backend](https://hub.docker.com/r/osrm/osrm-backend/), [frontend](https://hub.docker.com/r/osrm/osrm-frontend/)) on Debian and make sure they are as lightweight as possible. +We base our Docker images ([backend](https://github.com/Project-OSRM/osrm-backend/pkgs/container/osrm-backend), [frontend](https://hub.docker.com/r/osrm/osrm-frontend/)) on Debian and make sure they are as lightweight as possible. Older backend versions can be found on [Docker Hub](https://hub.docker.com/r/osrm/osrm-backend/). Download OpenStreetMap extracts for example from [Geofabrik](http://download.geofabrik.de/) @@ -65,7 +65,7 @@ The flag `-v "${PWD}:/data"` creates the directory `/data` inside the docker con docker run -t -v "${PWD}:/data" osrm/osrm-backend osrm-partition /data/berlin-latest.osrm docker run -t -v "${PWD}:/data" osrm/osrm-backend osrm-customize /data/berlin-latest.osrm -Note there is no `berlin-latest.osrm` file, but multiple `berlin-latest.osrm.*` files, i.e. `berlin-latest.osrm` is not file path, but "base" path referring to set of files and there is an option to omit this `.osrm` suffix completely(e.g. `osrm-partition /data/berlin-latest`). +Note there is no `berlin-latest.osrm` file, but multiple `berlin-latest.osrm.*` files, i.e. `berlin-latest.osrm` is not file path, but "base" path referring to set of files and there is an option to omit this `.osrm` suffix completely(e.g. `osrm-partition /data/berlin-latest`). docker run -t -i -p 5000:5000 -v "${PWD}:/data" osrm/osrm-backend osrm-routed --algorithm mld /data/berlin-latest.osrm @@ -84,7 +84,7 @@ In case Docker complains about not being able to connect to the Docker daemon ma After adding yourself to the `docker` group make sure to log out and back in again with your terminal. -We support the following images on Docker Cloud: +We support the following images in the Container Registry: Name | Description -----|------ @@ -96,7 +96,7 @@ Name | Description ### Building from Source -The following targets Ubuntu 16.04. +The following targets Ubuntu 22.04. For instructions how to build on different distributions, macOS or Windows see our [Wiki](https://github.com/Project-OSRM/osrm-backend/wiki). Install dependencies @@ -132,13 +132,13 @@ curl "https://router.project-osrm.org/route/v1/driving/13.388860,52.517037;13.38 The Node.js bindings provide read-only access to the routing engine. We provide API documentation and examples [here](docs/nodejs/api.md). -You will need a modern `libstdc++` toolchain (`>= GLIBCXX_3.4.20`) for binary compatibility if you want to use the pre-built binaries. +You will need a modern `libstdc++` toolchain (`>= GLIBCXX_3.4.26`) for binary compatibility if you want to use the pre-built binaries. For older Ubuntu systems you can upgrade your standard library for example with: ``` sudo add-apt-repository ppa:ubuntu-toolchain-r/test sudo apt-get update -y -sudo apt-get install -y libstdc++-5-dev +sudo apt-get install -y libstdc++-9-dev ``` You can install the Node.js bindings via `npm install osrm` or from this repository either via @@ -151,7 +151,7 @@ which will check and use pre-built binaries if they're available for this releas to always force building the Node.js bindings from source. -For usage details have a look [these API docs](docs/nodejs/api.md). +For usage details have a look [these API docs](docs/nodejs/api.md). An exemplary implementation by a 3rd party with Docker and Node.js can be found [here](https://github.com/door2door-io/osrm-express-server-demo). diff --git a/docs/nodejs/releasing.md b/docs/nodejs/releasing.md deleted file mode 100644 index 63c49f5cbc3..00000000000 --- a/docs/nodejs/releasing.md +++ /dev/null @@ -1,86 +0,0 @@ -# Releasing - -Releasing a new version of `node-osrm` is mostly automated using Travis CI. - -The version of `node-osrm` is locked to the same version as `osrm-backend`. Every `node-osrm` should have a `osrm-backend` release of the same version. Of course, only release a `node-osrm` after the release has been tagged in `osrm-backend`. - -These steps all happen on `master`. After the release is out, create a branch using the MAJOR.MINOR version of the release to document code changes made for that version. - -### Steps to release - -1. Update the `osrm_release` field in `package.json` to the corresonding git tag in `osrm-backend.` - - Confirm the desired OSRM branch and commit to `master`. - -1. Bump node-osrm version - - Update the `CHANGELOG.md` and the `package.json` version if needed. - -1. Check that Travis CI [builds are passing](https://travis-ci.org/Project-OSRM/node-osrm) for the latest commit on `master`. - -1. Publishing binaries - - If travis builds are passing then it's time to publish binaries by committing with a message containing `[publish binary]`. Use an empty commit for this. - - ``` - git commit --allow-empty -m "[publish binary] vMAJOR.MINOR.PATCH" - ``` - -1. Test - - Locally you can now test binaries. Cleanup, re-install, and run the tests like: - - ``` - make clean - npm install # will pull remote binaries - npm ls # confirm deps are correct - make test - ``` - -1. Tag - - Once binaries are published for Linux and OS X then its time to tag a new release and add the changelog to the tag: - - ``` - git tag vMAJOR.MINOR.PATCH -a - git push --tags - ``` - -1. Publish node-osrm. **we only do this for stable releases** - - First ensure your local `node-pre-gyp` is up to date: - - ``` - npm ls - ``` - - This is important because it is bundled during packaging. - - If you see any errors then do: - - ``` - rm -rf node_modules/node-pre-gyp - npm install node-pre-gyp - ``` - - Now we're ready to publish `node-osrm` to : - - ``` - npm publish - ``` - - Dependent apps can now pull from the npm registry like: - - ``` - "dependencies": { - "osrm": "^MAJOR.MINOR.PATCH" - } - ``` - - Or can still pull from the github tag like: - - ``` - "dependencies": { - "osrm": "https://github.com/Project-OSRM/node-osrm/archive/vMAJOR.MINOR.PATCH.tar.gz" - } - ``` diff --git a/docs/releasing.md b/docs/releasing.md index d28374f9ed0..cd6dc9cb84e 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -44,16 +44,16 @@ We may introduce forward-compatible changes: query parameters and response prope 1. Check out the appropriate release branch `x.y` 2. Make sure `CHANGELOG.md` is up to date. 3. Make sure the `package.json` on branch `x.y` has been committed. -4. Make sure all tests are passing (e.g. Travis CI gives you a :green_apple:) +4. Make sure all tests are passing (e.g. Github Actions CI gives you a :heavy_check_mark:) 5. Use an annotated tag to mark the release: `git tag vx.y.z -a` Body of the tag description should be the changelog entries. Commit should be one in which the `package.json` version matches the version you want to release. 6. Use `npm run docs` to generate the API documentation. Copy `build/docs/*` to `https://github.com/Project-OSRM/project-osrm.github.com` in the `docs/vN.N.N/api` directory 7. Push tags and commits: `git push; git push --tags` 8. On https://github.com/Project-OSRM/osrm-backend/releases press `Draft a new release`, write the release tag `vx.y.z` in the `Tag version` field, write the changelog entries in the `Describe this release` field - and press `Publish release`. Note that Travis deployments will create a release when publishing node binaries, so the release + and press `Publish release`. Note that Github Actions CI deployments will create a release when publishing node binaries, so the release may already exist. In which case the description should be updated with the changelog entries. 9. If not a release-candidate: Write a mailing-list post to osrm-talk@openstreetmap.org to announce the release -10. Wait until the travis build has been completed and check if the node binaries were published by doing: +10. Wait until the Github Actions build has been completed and check if the node binaries were published by doing: `rm -rf node_modules && npm install` locally. 11. For final releases run `npm publish` or `npm publish --tag next` for release candidates. -12. Bump version in `package.json` to `{MAJOR}.{MINOR+1}.0-latest.1` on the `master` branch after the release. +12. Bump version in `package.json` to `{MAJOR}.{MINOR+1}.0-unreleased` on the `master` branch after the release. diff --git a/docs/windows-deps.md b/docs/windows-deps.md index a4965d26555..32a59d5be37 100644 --- a/docs/windows-deps.md +++ b/docs/windows-deps.md @@ -1,80 +1,31 @@ # Building OSRM for Windows -## Dependencies - -Get a decent Windows with decent Visual Studio (14 at least for C++11 support). The published binaries are build with -VS2019 and Windows SDK8.1. - -In case you are using [prepacked Windows VM with VS2019](https://developer.microsoft.com/en-us/windows/downloads/virtual-machines/), you -have to install [Windows SDK 8.1](https://go.microsoft.com/fwlink/p/?LinkId=323507) - -Prepare directories for dependencies, build and target file location.Target directory ($target starting from that moment) should have /include and /lib subdirectories. +There is experimental support for building OSRM on Windows. -### Bzip2 - -1. Download from https://sourceware.org/pub/bzip2/bzip2-1.0.8.tar.gz -2. Start 'x64 Native Tools Command Prompt for VS2019' and change directory to unpacked source tree. -3. Issue `nmake /f makefile.msc` -4. Copy bzlib.h to $target\include and libbz2.lib to $target\lib - -### ZLib - -1. Download https://www.zlib.net/zlib-1.2.11.tar.gz -2. Start 'x64 Native Tools Command Prompt for VS2019' and change directory to unpacked source tree. -3. Switch to `contrib\vstudio\vc14` -4. If needed, open `zlibvc.sln` with Visual Studio and retarget to your version of compiler and SDK. -5. Issue `msbuild zlibvc.sln /p:BuildInParallel=true /p:Configuration=Release /p:Platform=x64 /m:` -6. Copy x64\ZlibStatRelease\zlibstat.lib to $target\lib\libz.lib, copy zlib.h and zconf.h to $target\include +## Dependencies -### ICU +You will need a modern Windows development stack (e.g. Visual Studio 17). The published binaries are built with +[Windows Server 2022](https://github.com/actions/runner-images/blob/main/images/win/Windows2022-Readme.md) Github hosted runners. -1. Download and unpack. - * https://github.com/unicode-org/icu/releases/download/release-66-1/icu4c-66_1-src.zip - * https://github.com/unicode-org/icu/releases/download/release-66-1/icu4c-66_1-data.zip -2. Do retarget if neededby openinig .\source\allinone\allinone.sln and editing projects -3. Start 'x64 Native Tools Command Prompt for VS2019' and change directory to unpacked source tree. -4. Run build: - msbuild .\source\allinone\allinone.sln /nologo /p:BuildInParallel=true /p:Configuration=Release /p:Platform=x64 /m: -5. Copy lib64\*.lib to $target\lib, copy include contents to $target\include -6. Copy bin64\*dll to any dir withing your $PATH. At the same time copy them to $target\lib +Dependencies are managed via [Conan](https://conan.io/) and built with [CMake](https://cmake.org/). -### Boost +## Building -1. Download and unpack https://dl.bintray.com/boostorg/release/1.73.0/source/boost_1_73_0.zip -2. Start 'x64 Native Tools Command Prompt for VS2019' and change directory to unpacked source tree. -3. Build b2: - bootstrap.bat --with-toolset=msvc-14.2 -4. Build boost: - b2 -a -d release state --build-type=minimal toolset=msvc-14.2 -q runtime-link=shared link=static address-model=64 --with-iostreams --with-test --with-thread --with-filesystem --with-date_time --with-system --with-program_options --with-regex --disable-filesystem2 -sHAVE_ICU=1 include=\include library-path=\lib -sZLIB_SOURCE=/zlib -zBZIP2_BINARY=libbz2 -sBZIP2_INCLUDE=\include -sBZIP2_LIBPATH=\lib -sICU_ICUUC_NAME=icuuc -sICU_ICUDT_NAME=icudt -sICU_ICUIN_NAME=icuin -sBUILD=boost_unit_test_framework -j -5. Copy `boost` subdirectory to \include and contents of `stage` to \lib +```bat +cmake -DENABLE_CONAN=ON -DENABLE_NODE_BINDINGS=ON -DCMAKE_BUILD_TYPE=%CONFIGURATION% -G "Visual Studio 17 2022" .. -### Expat +msbuild OSRM.sln ^ +/p:Configuration=%CONFIGURATION% ^ +/p:Platform=x64 ^ +/t:rebuild ^ +/p:BuildInParallel=true ^ +/m:%NUMBER_OF_PROCESSORS% ^ +/toolsversion:Current ^ +/clp:Verbosity=normal ^ +/nologo +``` -1. Download and unpack https://github.com/libexpat/libexpat/archive/R_2_2_9.zip -2. Start 'x64 Native Tools Command Prompt for VS2019' and change directory to unpacked source tree. -3. Configure build my calling cmake: - mkdir expat\build - cd expat\build - cmake -G"Visual Studio 16 2019" -DCMAKE_BUILD_TYPE=Release -DEXPAT_MSVC_STATIC_CRT=ON -DEXPAT_BUILD_EXAMPLES=OFF -DEXPAT_BUILD_TESTS=OFF -DEXPAT_SHARED_LIBS=OFF .. -4. Build expat: `msbuild expat.sln /nologo /p:Configuration=Release /p:Platform=x64` -5. Copy `Release\libexpat.*` to /lib. Copy `expat/lib/expat.h` and `expat/lib/expat_external.h` to /include -### LUA -1. Download and unpack https://www.lua.org/ftp/lua-5.3.5.tar.gz -2. Start 'x64 Native Tools Command Prompt for VS2019' and change directory to unpacked source tree. -3. Lua doesn't have native MSVC support, so you have to compile it by hand: - cd src - cl /MD /O2 /c /DLUA_COMPAT_5_2 *.c - ren lua.obj lua.o - ren luac.obj luac.o - link /LIB /OUT:lua5.3.5.dll *.obj -4. Copy `lua5.3.5.lib` to /lib. Copy `lua.h`,`lauxlib,h`,`lua.hpp`,`lualib.h`,`luaconf.h` to /include -### TBB -1. Download and unpack https://github.com/oneapi-src/oneTBB/archive/v2020.2.zip -2. Retarget by opening build\vs2013\makefile.sln -3. Start 'x64 Native Tools Command Prompt for VS2019' and change directory to unpacked source tree. -4. Switch to build\vs2013 and build: `msbuild makefle.sln /nologo /p:Configuration=Release /p:Platform=x64` -5. Copy x64/Release/*.{dll,lib} files to /lib and copy contents of include directory to /include