Merge pull request #9 from imphil/master

Separate build and installation process

.gitignore

@@ -5,8 +5,11 @@
 *.bak
 \#*\#
 
+# default build output directory
+/objdir
+
 # eclipse project files
 .externalToolBuilders
 .project
 .settings
-.pydevproject
+.pydevproject

.travis.yml

@@ -13,7 +13,6 @@ env:
  global:
     # Installation target
   - TARGET_BASE=$HOME/optimsoc
-  - TARGET=${TARGET_BASE}/current
   - PREBUILT_DEPLOY=optimsoc-prebuilt-deploy.py
   - PREBUILT_DEPLOY_URL=https://raw.githubusercontent.com/optimsoc/prebuilts/master/${PREBUILT_DEPLOY}
 
@@ -28,7 +27,7 @@ before_install:
 # Execute the build
 install:
  - source ${TARGET_BASE}/setup_prebuilt.sh
- - ./tools/install.py -d $TARGET --no-doc
+ - ./tools/build.py --no-doc
 
 script:
- -
+ -

Makefile

@@ -0,0 +1,26 @@
+version := $(shell tools/get-version.sh)
+
+OBJDIR := objdir
+INSTALL_PREFIX := /opt/optimsoc
+INSTALL_TARGET := $(INSTALL_PREFIX)/$(version)
+
+build:
+	tools/build.py -o $(OBJDIR)
+
+install: build
+	mkdir -p $(INSTALL_TARGET)
+	cp -r $(OBJDIR)/dist $(INSTALL_TARGET)
+
+dist: build
+	tar -cz --directory $(OBJDIR) --exclude examples \
+		--transform "s/dist/$(version)/" \
+		-f $(OBJDIR)/optimsoc-$(version)-base.tar.gz dist
+	tar -cz --directory $(OBJDIR) \
+		--transform "s/dist/$(version)/" \
+		-f $(OBJDIR)/optimsoc-$(version)-examples.tar.gz dist/examples
+
+	@echo
+	@echo The binary distribution packages have been written to
+	@echo $(OBJDIR)/optimsoc-$(version)-base.tar.gz and
+	@echo $(OBJDIR)/optimsoc-$(version)-examples.tar.gz
+

README.installed

@@ -1,3 +1,3 @@
 This is the Open Tiled Manycore System-on-Chip (OpTiMSoC). For more
 information please visit http://www.optimsoc.org or read the user
-guide in doc/UserGuide.pdf.
+guide in doc/user_guide.pdf.

doc/release-howto.md

@@ -0,0 +1,39 @@
+OpTiMSoC Release HOWTO
+======================
+
+What needs to be done to release a new OpTiMSoC version?
+
+
+OpTiMSoC releases are named YEAR.N, where YEAR is the current year
+(four-digit), and N is a incrementing number starting at 1 representing
+the Nth release in YEAR.
+
+1. Tag the source code in git on the `master` branch
+
+   We use annotated tags for releases to record the release author and the
+   release date properly. All release version tags start with "v".
+
+   ```
+   git tag -am "Release vYEAR.N" vYEAR.N
+   ```
+
+2. Build the code for this release
+   ```
+   cd $OPTIMSOC_SRC
+   make dist
+   ```
+   The resulting binary packages are named
+   `objdir/optimsoc-YEAR.N-[base|examples].tar.gz`
+
+3. Test the release and make sure it works.
+
+4. Push the tag to the remote repository:
+   ```
+   git push origin vYEAR.N
+   ```
+
+5. Follow the
+   [GitHub documentation](https://help.github.com/articles/creating-releases/)
+   on how to create a release.
+
+   In this process you can also upload the created binary packages.

doc/user_guide/Makefile

@@ -2,6 +2,8 @@ PDFLATEX ?= pdflatex
 LATEXML ?= latexml
 LATEXMLPOST ?= latexmlpost
 
+OBJDIR := .
+
 TEXFILES = user_guide-preamble.tex \
            user_guide-title.tex \
            user_guide-changes.tex \
@@ -15,19 +17,22 @@ TEXFILES = user_guide-preamble.tex \
 
 all: pdf html
 
-html: html/user_guide.xhtml
+html: $(OBJDIR)/html/user_guide.xhtml
 
-pdf: user_guide.pdf
+pdf: $(OBJDIR)/user_guide.pdf
 
-%.pdf: %.tex $(TEXFILES) Makefile
-	$(PDFLATEX) -interaction nonstopmode $*.tex
+$(OBJDIR)/%.pdf: %.tex $(TEXFILES) Makefile
+	$(PDFLATEX) -output-directory=$(OBJDIR) -interaction nonstopmode $*.tex
 	# Run again to get references right
-	$(PDFLATEX) -interaction nonstopmode $*.tex
+	$(PDFLATEX) -output-directory=$(OBJDIR) -interaction nonstopmode $*.tex
 
-html/%.xhtml: %-html.tex $(TEXFILES)
-	$(LATEXML) --dest=$*.xml $*-html.tex
-	$(LATEXMLPOST) --dest=html/$*.xhtml $*.xml
+$(OBJDIR)/html/%.xhtml: %-html.tex $(TEXFILES)
+	$(LATEXML) --dest=$(OBJDIR)/$*.xml $<
+	$(LATEXMLPOST) --dest=$(OBJDIR)/html/$*.xhtml $(OBJDIR)/$*.xml
 
 clean:
-	rm -rf *.pdf *.aux *.toc *.out *.log *.xml html/
+	rm -rf $(OBJDIR)/*.pdf $(OBJDIR)/*.aux $(OBJDIR)/*.toc $(OBJDIR)/*.out \
+		$(OBJDIR)/*.log $(OBJDIR)/*.xml $(OBJDIR)/html
+
 
+.PHONY: clean

doc/user_guide/user_guide-installation.tex

@@ -26,16 +26,17 @@ \section{Prerequisites}
 sudo apt-get -y install git python build-essential automake autoconf
 \end{lstlisting}
 
-\section{Get OpTiMSoC -- Quick Start}
+\section{Option 1: Install the OpTiMSoC binary distribution (recommended)}
 
 The most simple way to get started is with the release packages. You
 can find the OpTiMSoC releases here:
 \url{https://github.com/optimsoc/sources/releases}. With the release
-you can find the distribution packets that need to be extracted to
-\verb|/opt/optimsoc|. There are two packages: the \verb|base| package
-contains the programs, libraries and tools to get started. The
-\verb|examples| package contains prebuilt verilator simulations for
-the real quick start.
+you can find the distribution packets that can be extracted into any
+directory and used directly from there. The recommended default is to
+install OpTiMSoC into \verb|/opt/optimsoc|. There are two packages:
+the \verb|base| package contains the programs, libraries and tools
+to get started. The \verb|examples| package contains prebuilt verilator
+simulations for the real quick start.
 
 For example take the 2015.1 release and download both \verb|base| and
 \verb|examples|. Then create the base folder and extract the package:
@@ -51,10 +52,11 @@ \section{Get OpTiMSoC -- Quick Start}
 the pre-installed environment source script:
 
 \begin{lstlisting}
-source /opt/optimsoc/2015.1/setup.sh
+cd /opt/optimsoc/2015.1
+source optimsoc-environment.sh
 \end{lstlisting}
 
-We encourage you to put this line into your \verb|~/.bashrc|.
+We encourage you to put this code into your \verb|~/.bashrc|.
 
 Now you are near to get started, but you need some programs to build
 software to run in OpTiMSoC and execute the verilator-based
@@ -83,7 +85,7 @@ \section{Get OpTiMSoC -- Quick Start}
 
 You are now ready to go to the tutorials.
 
-\section{Get OpTiMSoC -- Build yourself}
+\section{Option 2: Build OpTiMSoC from sources}
 
 You can also build OpTiMSoC from the sources. This options usually
 becomes standard if you start developing for or around OpTiMSoC. The
@@ -133,12 +135,12 @@ \section{Get OpTiMSoC -- Build yourself}
 
 \end{docnote}
 
-\subsection{Pre-requisites}
+\subsection{Prerequisites}
 
 You will need some programs to build OpTiMSoC, e.g., on Ubuntu 14.04:
 
 \begin{lstlisting}
-sudo apt-get install autoconf automake libtool tcl texlivetexlive-latex-extra texlive-fonts-extra
+sudo apt-get install autoconf automake libtool tcl texlive texlive-latex-extra texlive-fonts-extra
 \end{lstlisting}
 
 \subsection{Get the sources}
@@ -150,10 +152,39 @@ \subsection{Get the sources}
 cd optimsoc-sources
 \end{lstlisting}
 
-\subsection{Run installer}
+\subsection{Build the code}
 
-Now simply run the installer to install:
+OpTiMSoC contains a Makefile which controls the whole build process. Building is
+as simple as calling (inside the top-level source directory)
 
 \begin{lstlisting}
-./tools/install.py -d /opt/optimsoc/2015.1
+make
+\end{lstlisting}
+
+\subsection{Install the code}
+To install OpTiMSoC to the default location in \verb|/opt/optimsoc/VERSION|
+it's sufficient to run
+
+\begin{lstlisting}
+sudo make install
+\end{lstlisting}
+
+You can also modify the target directory using environment variables passed to
+make. This is especially useful if you don't have enough permissions to
+write to \verb|/opt/optimsoc|.
+
+\begin{itemize}
+  \item Use \verb|INSTALL_PREFIX| to change the installation prefix from
+    \verb|/opt/optimsoc| to something else. The installation will then go
+    into \verb|INSTALL_PREFIX/VERSION|.
+  \item Use \verb|INSTALL_TARGET| to fully override the installation path.
+    The installation will then go exactly into this directory.
+\end{itemize}
+
+\begin{lstlisting}
+# recommended option: use INSTALL_PREFIX
+make install INSTALL_PREFIX=~/optimsoc
+
+# full control for special cases: use INSTALL_TARGET
+make install INSTALL_TARGET=~/optimsoc-testversion
 \end{lstlisting}

src/host/sim/src/share/Makefile.verilator.inc

@@ -3,6 +3,8 @@
 CXX ?= g++
 CFLAGS ?= -g -Wall
 VERILATOR ?= verilator
+OBJDIR := .
+SRCDIR := $(PWD)
 
 INC=$(shell pkg-config --cflags optimsoc-sim)
 LIB=$(shell pkg-config --libs optimsoc-sim)
@@ -11,18 +13,20 @@ LIB+=$(shell pkg-config --libs verilator)
 
 VERILATOR_INCDIR=$(shell pkg-config --variable=includedir verilator)
 
-build-verilator: $(TBENCH)
+build-verilator: $(OBJDIR)/$(TBENCH)
 
-flags = -CFLAGS "$(INC)" -LDFLAGS "$(LIB) -pthread" --exe --trace --sv --unroll-count 256 --Wno-fatal
+flags = -CFLAGS "$(INC) -I$(OBJDIR)" -LDFLAGS "$(LIB) -pthread" --exe --trace --sv --unroll-count 256 --Wno-fatal
 
-$(TBENCH): verilator.vc
-	$(VERILATOR) --cc -f verilator.vc $(TBENCH).cpp $(flags) -o ../$(TBENCH)
-	make -C obj_dir -f V$(TBENCH).mk
+$(OBJDIR)/$(TBENCH): $(OBJDIR)/verilator.vc
+	$(VERILATOR) --Mdir $(OBJDIR)/obj_dir --cc  \
+		-f $(OBJDIR)/verilator.vc \
+		$(SRCDIR)/$(TBENCH).cpp $(flags) -o $(OBJDIR)/$(TBENCH)
+	make -C $(OBJDIR)/obj_dir -f V$(TBENCH).mk
 
-verilator.vc:
-	tclsh $(OPTIMSOC_TCL)/optimsoc_verilator.tcl build.tcl
+$(OBJDIR)/verilator.vc:
+	VERILATOR_VC_FILE=$(OBJDIR)/verilator.vc tclsh \
+		$(OPTIMSOC_TCL)/optimsoc_verilator.tcl $(SRCDIR)/build.tcl
 
 clean:
-	rm -rf obj_dir *.o
+	rm -rf $(OBJDIR)/obj_dir $(OBJDIR)/*.o
 
-.PHONY: verilator.vc