From 9d80a5a11e49726a62e7642bce364e8c2636ad40 Mon Sep 17 00:00:00 2001 From: Hisham Muhammad Date: Mon, 2 Jul 2018 21:48:53 -0300 Subject: Docs: updated Changelog for LuaRocks 3.0 --- CHANGELOG.md | 203 ++++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 151 insertions(+), 52 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 798f3c5f..d4a49836 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,56 +1,33 @@ -What's new in LuaRocks 3.0 -========================== +## What's new in LuaRocks 3.0 -* *Breaking change:* The support for deprecated unversioned paths - (e.g. `/usr/local/lib/luarocks/rocks/` and `/etc/luarocks/config.lua`) - was removed, LuaRocks will now only create and use paths versioned - to the specific Lua version in use - (e.g. `/usr/local/lib/luarocks/rocks-5.3/` and `/etc/luarocks/config-5.3.lua`). -* *New rockspec format:* if you add `rockspec_format = "3.0"` to your - rockspec, you can use all features listed in the section "[Rockspec 3.0]" below. - Note that these rockspecs will only work with LuaRocks 3.0 and above, but - older versions will detect that directive and fail gracefully, giving the - user a message telling them to upgrade. -* *New feature:* [namespaces](https://github.com/luarocks/luarocks/wiki/Namespaces): - you can use `luarocks install user/package` to install a package from a - specific user of the repository. -* *New command:* `luarocks test`. It runs a rock's test suite, as specified - in the new `test` section of the rockspec file. It also does some - autodetection, so it already works with many existing rocks as well. -* *New command:* `luarocks which`. Given the name of an installed, it tells - you which rock it is a part of. For example, `luarocks which lfs` - will tell you it is a part of `luafilesystem` (and give the full - path name to the module). In this sense, `luarocks which` is the - dual command to `luarocks show`. -* *New flag* `--temp-key` for `luarocks upload`, allowing you to easily - upload rocks into an alternate account without disrupting the - stored configuration of your main account. -* *New flag* `--dev`, for enabling development-branch sub-repositories. - This adds support for easily requesting `dev` modules from LuaRocks.org, as in: - `luarocks install --dev luafilesystem`. The list of URLs configured - in `rocks_servers` is prepended with a list containing "/dev" in their paths. -* `luarocks path` now exports versioned variables `LUA_PATH_5_x` and - `LUA_CPATH_5_x` instead of `LUA_PATH` and `LUA_CPATH` - when those are in use in your system. -* Package paths are sanitized to only reference the current Lua version. - For example, if you have `/some/dir/lua/5.1/` in your `$LUA_PATH` and - you are running Lua 5.2, `luarocks.loader` and the `luarocks` command-line - tool will convert it to `/some/dir/lua/5.2/`. -* Wrappers installed using `--tree` now prepend the tree's prefix to their - package paths. -* `luarocks-admin` commands no longer creates an `index.html` file in the - repository by default (it does update it if it alroady exists) -* `luarocks-admin add` now works with `file://` repositories +- [New rockspec format](#new-rockspec-format) +- [New commands](#new-commands), including [luarocks init](https://github.com/luarocks/luarocks/wiki/Project:-LuaRocks-per-project-workflow) for per-project workflows +- [New flags](#new-flags), including `--lua-dir` and `--lua-version` for using multiple Lua installs with a single LuaRocks +- [New build system](#new-build-system) +- [General improvements](#general-improvements), including [namespaces](https://github.com/luarocks/luarocks/wiki/Namespaces) +- [User-visible changes](#user-visible-changes), including some *breaking changes* +- [Internal changes](#internal-changes) -Rockspec 3.0 ------------- +### New rockspec format -These features are only enabled if `rockspec_format = "3.0"` is set in the rockspec: +*New rockspec format:* if you add `rockspec_format = "3.0"` to your rockspec, +you can use a number of new features. Note that these rockspecs will only work +with LuaRocks 3.0 and above, but older versions will detect that directive and +fail gracefully, giving the user a message telling them to upgrade. Rockspecs +without the `rockspec_format` directive are interpreted as having format 1.0 +(the same format from LuaRocks series 1.x and 2.x) and are still supported. + +The following features are only enabled if `rockspec_format = "3.0"` is set in +the rockspec: * Build type `builtin` is the default if `build.type` is not specified. -* New table `build_dependencies`: dependencies used only for running `luarocks build` - but not when installing binary rocks. +* The `builtin` type auto-detects modules using the same heuristics as + `write_rockspec` (for example, if you have a `src` directory). With + auto-detection of the build type and modules, many rockspecs don't + even need an explicit `build` table anymore. +* New table `build_dependencies`: dependencies used only for running + `luarocks build` but not when installing binary rocks. * New table `test_dependencies`: dependencies used only for running `luarocks test` * New table `test`: settings for configuring the behavior of `luarocks test`. Supports a `test.type` field so that the test backend can be specified. @@ -74,14 +51,136 @@ These features are only enabled if `rockspec_format = "3.0"` is set in the rocks * Patches added in `patches` can create and delete files, following standard patch rules. -Internal changes ----------------- +### New commands + +* *New command:* `luarocks init`. This command performs the setup for using + LuaRocks in a "project directory": + * it creates a `lua_modules` directory in the current directory for + storing rocks + * it creates a `.luarocks/config-5.x.lua` local configuration file + * it creates `lua` and `luarocks` wrapper scripts in the current + directory that are configured to use `lua_modules` and + `.luarocks/config-5.x.lua` + * if there are no rockspecs in the current directory, it creates one + based on the directory name and contents. +* *New command:* `luarocks test`. It runs a rock's test suite, as specified + in the new `test` section of the rockspec file. It also does some + autodetection, so it already works with many existing rocks as well. +* *New command:* `luarocks which`. Given the name of an installed, it tells + you which rock it is a part of. For example, `luarocks which lfs` + will tell you it is a part of `luafilesystem` (and give the full + path name to the module). In this sense, `luarocks which` is the + dual command to `luarocks show`. + +### New flags + +* *New flags* `--lua-dir` and `--lua-version` which can be used with + all commands. This allows you to specify a Lua version and installation + prefix at runtime, so a single LuaRocks installation can be used + to manage packages for any Lua version. It is no longer necessary to + install separate copies of LuaRocks to manage packages for Lua 5.x + and 5.y. +* *New flags* added to `luarocks show`: `--porcelain`, giving a stable + script-friendly output (named after the Git `--porcelain` flag that + serves the same purpose) and `--rock-license`. +* *New flag* `--temp-key` for `luarocks upload`, allowing you to easily + upload rocks into an alternate account without disrupting the + stored configuration of your main account. +* *New flag* `--dev`, for enabling development-branch sub-repositories. + This adds support for easily requesting `dev` modules from LuaRocks.org, as in: + `luarocks install --dev luafilesystem`. The list of URLs configured + in `rocks_servers` is prepended with a list containing "/dev" in their paths. +* `luarocks config`, when called with no arguments, now displays your + entire active configuration, using the same Lua syntax as the configuration + file. It is sensitive to the flags given to it (`--tree`, `--lua-dir`, etc.) + so it presents the resulting configuration produced by loading the + currently-active configuration files and the given flags. + +### New build system + +*New build system*: the `configure` and `Makefile` scripts were completely +overhauled, making use of LuaRocks 3 features to greatly simplify them: + +* Much of the detection and configuration work they performed were moved + to runtime, to make LuaRocks more dynamic and resilient to environment + changes +* The system-package-manager-friendly mode is still available, as the + default target (`make`, formerly `make build`). +* The LuaRocks-as-a-rock mode (`make bootstrap`) is also still available, + and was greatly simplified: it no longer uses custom Makefiles: + LuaRocks installs itself using `luarocks make`, and its own rockspec + uses the `builtin` build mode. +* A new build mode: `make binary` compiles all of LuaRocks into a single + executable, bundling various Lua modules to make it self-sufficient, + such as LuaFileSystem, LuaSocket and LuaSec. + * For version 3.0, this will remain as an option, as we evaluate + its suitability moving forward to become the default mode of + distribution. + * The goal is to eventually use this mode to produce the Windows + version of LuaRocks. We currently include an experimental + `make windows-binary` target which builds a Windows version + using the MinGW-w64 cross-compiler on Linux. + +### General improvements + +* *New feature:* [namespaces](https://github.com/luarocks/luarocks/wiki/Namespaces): + you can use `luarocks install user/package` to install a package from a + specific user of the repository. +* Improved defaults for finding external libraries on Linux and Windows. +* Detection of the Lua library and header directories is now done at runtime. + This uses the same machinery that LuaRocks employs for `external_dependencies` + in general (with some added logic to cope with the unfortunate + rampant inconsistency in naming of Lua libraries and header paths + due to lack of upstream standardization). +* `luarocks-admin add` now works with `file://` repositories +* some UI improvements in `luarocks list` and `luarocks search`. +* Preliminary support for the upcoming Lua 5.4: LuaRocks is written in + the common dialect supporting Lua 5.1-5.3 and LuaJIT, but since a + single installation can manage packages for any Lua version now, + it can already manage packages for Lua 5.4 even though that's not + out yet. + +### User-visible changes + +* *Breaking change:* The support for deprecated unversioned paths + (e.g. `/usr/local/lib/luarocks/rocks/` and `/etc/luarocks/config.lua`) + was removed, LuaRocks will now only create and use paths versioned + to the specific Lua version in use + (e.g. `/usr/local/lib/luarocks/rocks-5.3/` and `/etc/luarocks/config-5.3.lua`). +* *Breaking changes:* `luarocks path` now exports versioned variables + `LUA_PATH_5_x` and `LUA_CPATH_5_x` instead of `LUA_PATH` and `LUA_CPATH` + when those are in use in your system. +* Package paths are sanitized to only reference the current Lua version. + For example, if you have `/some/dir/lua/5.1/` in your `$LUA_PATH` and + you are running Lua 5.2, `luarocks.loader` and the `luarocks` command-line + tool will convert it to `/some/dir/lua/5.2/`. +* LuaRocks now uses `dev` instead of `scm` as the favored version identifier + to describe development versions of a rock, aligning it with the terminology + used in https://luarocks.org. It still understands `scm` as a + compatibility fallback. +* LuaRocks no longer conflates modules `foo` and `foo.init` as being the + same in its internal manifest. Instead, the `luarocks.loader` module + is adapted to handle the `.init` case. +* Wrappers installed using `--tree` now prepend the tree's prefix to their + package paths. +* `luarocks-admin` commands no longer creates an `index.html` file in the + repository by default (it does update it if it already exists) + +### Internal changes -* Modules needed by `luarocks.loader` were moved into the `luarocks.core` namespace. +* Major improvements in the test suite done by @georgeroman as part of the ongoing + Google Summer of Code 2018 program. The coverage improvements and test suite + speed-ups have been essential in getting the sprint towards LuaRocks 3.0 more + efficient and reliable! +* Modules needed by `luarocks.loader` were moved below the `luarocks.core` namespace. Modules in `luarocks.core` only depend on other `luarocks.core` modules. (Notably, `luarocks.core` does not use `luarocks.fs`.) -* Modules representing `luarocks` commands were moved into the `luarocks.cmd` namespace. -* Modules representing `luarocks-admin` commands were moved into the `luarocks.admin.cmd` namespace. +* Modules representing `luarocks` commands were moved into the `luarocks.cmd` namespace, + and `luarocks.command_line` was renamed to `luarocks.cmd`. Eventually, all CLI-related + code will live under `luarocks.cmd`, as we move towards a clean CLI-API separation, + in preparation for a stable public API. +* Likewise, modules representing `luarocks-admin` commands were moved into the + `luarocks.admin.cmd` namespace. * New internal objects for representing interaction with the repostories: `luarocks.queries` and `luarocks.results` * Type checking rules of file formats were moved into the `luarocks.type` namespace. -- cgit v1.2.3-55-g6feb