Docu update

bin/yupdate

@@ -416,6 +416,26 @@ HELP
   class Installer
     include YUpdate::Logger
 
+    attr_reader :src_dir
+
+    # @param src_dir [String] the source directory with unpacked sources
+    def initialize(src_dir)
+      @src_dir = src_dir
+    end
+
+    # install the sources to the inst-sys
+    def install
+      Dir.mktmpdir do |tmp|
+        # first install the files into a temporary location
+        # using "rake install DESTDIR=..."
+        install_sources(tmp)
+        # then find the changed files and update them in the inst-sys
+        copy_to_system(tmp)
+      end
+    end
+
+  private
+
     # globs for ignored some files
     SKIP_FILES = [
       # vim temporary files
@@ -431,20 +451,20 @@ HELP
     ].freeze
 
     # install the sources to the specified (temporary) directory
-    def install_sources(src, target)
+    def install_sources(target)
       msg "Preparing files..."
 
       # check for Makefile.cvs, we cannot install packages using autotools
-      makefile_cvs = Dir["#{src}/**/Makefile.cvs"].first
+      makefile_cvs = Dir["#{src_dir}/**/Makefile.cvs"].first
       if makefile_cvs
         raise "Found Makefile.cvs, autotools based packages cannot be installed!"
       end
 
-      rakefile = Dir["#{src}/**/Rakefile"].first
+      rakefile = Dir["#{src_dir}/**/Rakefile"].first
       raise "Rakefile not found, cannot install the package" unless rakefile
 
-      src = File.dirname(rakefile)
-      Dir.chdir(src) do
+      src_dir = File.dirname(rakefile)
+      Dir.chdir(src_dir) do
         `rake install DESTDIR=#{target.shellescape} 2> /dev/null`
       end
     end
@@ -618,7 +638,7 @@ HELP
       if arg1 && arg2
         # update from github
         install_from_github(arg1, arg2)
-      elsif arg1.start_with?("http")
+      elsif arg1.start_with?("http") && arg1.end_with?(".tar.gz")
         # upgrade from URL
         install_from_tar(arg1)
       else
@@ -655,11 +675,8 @@ HELP
     end
 
     def install_sources(src_dir)
-      Dir.mktmpdir do |target_dir|
-        i = Installer.new
-        i.install_sources(src_dir, target_dir)
-        i.copy_to_system(target_dir)
-      end
+      i = Installer.new(src_dir)
+      i.install
     end
 
     # prepare the inst-sys for installation:

doc/yupdate.md

@@ -32,14 +32,14 @@ and use the `ypdate` script to apply the changes on top of the self-update.
 
 ## Installation
 
-yupdate should run in the inst-sys. Since SLE15-SP2/openSUSE
+The `yupdate` script should run in the inst-sys. Since SLE15-SP2/openSUSE
 Leap 15.2, openSUSE Tumbleweed 2020xxxx, it ~~is~~ will be preinstalled.
 
 For older releases, run:
 
-```
-inst-sys# wget https://raw.githubusercontent.com/yast/yast-installation/master/bin/yupdate
-inst-sys# chmod +x ./yupdate
+```shell
+wget https://raw.githubusercontent.com/yast/yast-installation/master/bin/yupdate
+chmod +x ./yupdate
 ```
 
 You can also use this command to update the included script
@@ -53,7 +53,11 @@ This script is intended to help in the following scenarios.
 
 To make a directory in the inst-sys writable run command
 
-`yupdate overlay create <dir>` this will create a writable overlay
+```shell
+yupdate overlay create <dir>
+```
+
+this will create a writable overlay
 above the specified directory. If you do not specify any directory
 it will create writable overlays for the default YaST directories.
 
@@ -62,21 +66,127 @@ or by other tools like `sed`.
 
 ### Patch YaST from GitHub Sources
 
+To install an YaST package directly from the GitHub repository use command
+```shell
+yupdate patch <github_slug> <branch>
+```
+
+where `github_slug` is a `user`/`repository` name, if the `user` value is missing
+the default "yast" is used. The `branch` in the source branch to install, for example
+`master` or `SLE-15-SP2`.
+
+
+#### Examples
+
+```shell
+# install the latest version of yast2-installation from upstream
+yupdate patch yast-installation master
+# install from a fork
+yupdate patch my_fork/yast-installation my_branch
+```
+
+#### Notes
+
+- Make sure that you use a branch compatible with the running inst-sys,
+  installing the latest version in an older release might not work
+  as expect, the installer might crash or behave unexpectedly.
+- There is no dependency resolution, if the new installed package
+  requires newer dependant packages then they must be installed manually.
+
 ### Patch YaST from Locally Modified Sources
 
+Installing from GitHub sources is easy, but sometimes you do not want to
+push every single change to GitHub, you would like to just use the current
+files from you local Git checkout.
+
+In that case run
+
+```shell
+rake server
+```
+
+in your Git checkout, which will run a web server providing source tarball
+similar to the GitHub archive used in the previous case.
+
+*Note: You need "yast-rake" Ruby gem version 0.2.37 or newer.*
+
+Then run
+
+```shell
+yupdate patch <host_name>
+```
+
+where `<host_name>`  is the machine host name or the IP address. This will
+by default is port 8000, if the server uses another port just add `:` followed
+by the port number.
+
+#### Patching Multiple Packages
+
+The `yast patch` command installs the sources from all running `rake server`
+servers. If you need to update sources from several packages you can just
+run `rake server` in all of them and install them with a single `yupdate`
+call.
+
 ### Patch YaST from a Generic Tarball Archive
 
+This is similar to the previous cases, but the source tarball is not generated
+dynamically by a server, but it is a statically hosted file.
+
+Example:
+
+```shell
+yupdate patch http://myserver.example.com/test/yast2.tar.gz
+```
 
 ## Other Commands
 
+### Listing OverlayFS Mounts
+
+To see the list of mounted OverlayFS run
+
+```shell
+yupdate overlay list
+```
+
+### Listing Updated Files
+
+To see the list of changed files
+
+```shell
+yupdate overlay files
+```
+
+### Displaying Changes in the System
+
+To see the applied changes to the system run
+
+```shell
+yupdate overlay diff
+```
+
+This will display a diff for all changed files, it does not report
+deleted or new files.
+
+### Restoring the System
+
+To revert all changes run
+
+```shell
+yupdate overlay reset
+```
+
+This will remove *all* OverlayFS mounts and restore the system to the original
+state.
+
+
 ## Limitations
 
 - The script only works with Ruby source files, it cannot compile and
   install C/C++ or other sources (the compiler and development libraries
   are missing in the inst-sys)
 - Works only with the packages which use `Rakefile` for installation,
-  it does not work with autotools based packages (autoconf/automake
-  is also missing in the inst-sys)
+  it does not work with autotools based packages (again, autoconf/automake
+  are also missing in the inst-sys)
 
 
 ## Alternative