From 360895eda5390bc7e49d4ec368422577aa1b5a7e Mon Sep 17 00:00:00 2001
From: "Hazal2.Veziroglu@live.uwe.ac.uk" <hazal2.veziroglu@live.uwe.ac.uk>
Date: Wed, 4 Dec 2024 01:20:03 +0000
Subject: [PATCH] Update file README.md
---
Worksheet_1/README.md | 189 +++++++++++++++++++++++++++++-------------
1 file changed, 131 insertions(+), 58 deletions(-)
diff --git a/Worksheet_1/README.md b/Worksheet_1/README.md
index dc4aefd..6b75544 100644
--- a/Worksheet_1/README.md
+++ b/Worksheet_1/README.md
@@ -1,84 +1,157 @@
-# Worksheet 1: Assembly Programming with Docker Integration
-
-This project is part of the **Worksheet 1** task, focusing on assembly programming and integration with Docker for build and run processes.
-
-## Project Overview
-
-This repository contains assembly language programs and supporting files to demonstrate basic programming concepts in assembly language. The workflow involves writing assembly code, integrating it with C for execution, and containerizing the build process using Docker.
-
-### Files in the Repository
-
-- **Assembly Files**
- - `task1.asm`: First task in assembly programming.
- - `task2.asm`: Second task in assembly programming.
- - `task3.asm`: Third task in assembly programming.
-
-- **C Files**
- - `driver.c`: Main driver file that calls the assembly program.
- - `print_int.c`: Helper function to print integers.
-
-- **Include Files**
- - `asm_io.asm` and `asm_io.inc`: Assembly IO routines.
-
-- **Build Files**
- - `Makefile`: Automates the build process.
- - `Dockerfile`: Containerizes the build and execution process.
-## Getting Started
-
-### Prerequisites
+# Worksheet 1: Assembly Programming with Docker Integration
-- **Docker**: Ensure Docker is installed on your machine.
-- **NASM**: An assembler for x86 assembly.
-- **GCC**: A C compiler to link the assembly and C code.
+This project is part of the **Worksheet 1** task, focusing on assembly programming and integration with Docker for build and run processes. Due to connectivity issues with `csctcloud`, Docker was used as a workaround to set up a Linux environment directly from Visual Studio Code. This approach allowed for seamless development, testing, and debugging of assembly programs.
-### Building and Running
+---
-1. **Using Docker**:
- - Build the Docker container:
- ```bash
- docker build -t asm_project .
- ```
- - Run the container:
- ```bash
- docker run --rm asm_project
- ```
+## Project Overview
-2. **Locally**:
- - Compile using `make`:
+This repository contains assembly language programs and supporting files to demonstrate basic programming concepts in assembly language. The workflow involves:
+- Writing assembly code.
+- Integrating it with C for execution.
+- Automating builds with a `Makefile`.
+- Running the tasks in a containerized Linux environment using Docker.
+
+---
+
+## Docker Integration
+
+### Why Docker?
+`csctcloud` environment was unavailable due to connectivity issues. To continue working efficiently, Docker was used to:
+- Set up a 32-bit Linux environment required for assembly programming.
+- Provide a consistent environment directly accessible through Visual Studio Code for editing, building, and running tasks.
+
+### Dockerfile Configuration
+The Dockerfile is configured to create an environment with all necessary tools and dependencies for assembly programming. The following packages are installed during the build process:
+
+1. **`nasm`**: An assembler required to compile `.asm` files into object files.
+2. **`gcc`**: Used to compile C programs and link them with assembly object files.
+3. **`gcc-multilib`**: Provides support for compiling and linking 32-bit binaries on a 64-bit system.
+4. **`libc6-dev`**: Development libraries for the GNU C Library (glibc), providing headers and support for 32-bit compilation.
+
+### Docker Build Process
+During the Docker image build, these dependencies are installed with the following commands:
+```bash
+apt update
+apt install -y nasm gcc
+apt install -y gcc-multilib
+apt install -y libc6-dev
+```
+---
+
+### Using Docker
+1. **Build the Docker Image**:
+ ```bash
+ docker build -t asm_project .
+ ```
+2. **Run the Docker Container**:
+ ```bash
+ docker run -it --rm -v $(pwd):/workspace -w /workspace asm_project
+ ```
+3. **Inside the Container**:
+ - Compile all tasks:
```bash
make
```
- - Run the program:
+ - Run each task:
+ - Task 1:
+ ```bash
+ ./src/task1
+ ```
+ - Task 2:
+ ```bash
+ ./src/task2
+ ```
+ - Task 3:
+ ```bash
+ ./src/task3
+ ```
+ - Clean up object files and executables:
```bash
- ./program
+ make clean
```
+---
+
+## Tasks and Implementations
+
+### Task 1: Adding Two Integers
+- **File**: `task1.asm`
+- **Description**: This task involves writing an assembly program that:
+ 1. Adds two integers stored in global memory.
+ 2. Prints the result using the helper function `print_int`.
+
+#### How to Run:
+1. Compile and link:
+ ```bash
+ make task1
+ ```
+2. Run the program:
+ ```bash
+ ./src/task1
+ ```
+
+---
+
+### Task 2: Loops and Conditionals
+- **File**: `task2.asm`
+- **Description**: This task involves implementing:
+ 1. A loop to sum an array of integers.
+ 2. User input validation (e.g., checking if a number is between 50 and 100).
+
+#### How to Run:
+1. Compile and link:
+ ```bash
+ make task2
+ ```
+2. Run the program:
+ ```bash
+ ./src/task2
+ ```
+
+---
## Project Structure
+```
worksheet_1/
-├── README.md # Project documentation (to be created or updated by you)
-├── Makefile # Build file for automating compilation
-├── Dockerfile # Docker configuration for containerized builds
-├── src/ # Directory containing all source files
-│ ├── asm_io.asm # Provided Assembly IO code
-│ ├── asm_io.inc # Provided IO include file
-│ ├── driver.c # Main C program calling assembly functions
-│ ├── print_int.c # Helper C program for printing integers
-│ ├── task1.asm # Assembly code for Task 1
-│ ├── task2.asm # Assembly code for Task 2
-│ ├── task3.asm # Assembly code for Task 3
-
+├── README.md # Project documentation
+├── Makefile # Automates the build process
+├── Dockerfile # Configures the Linux environment
+├── src/ # Directory containing all source files
+│ ├── asm_io.asm # Provided Assembly IO code
+│ ├── asm_io.inc # Provided IO include file
+│ ├── driver.c # Main C program calling assembly functions
+│ ├── print_int.c # Helper C program for printing integers
+│ ├── task1.asm # Assembly code for Task 1
+│ ├── task2.asm # Assembly code for Task 2
+│ ├── task3.asm # Assembly code for Task 3
+```
+---
+## Screenshots and Outputs
+
+To fulfill the documentation requirements, include screenshots of:
+1. **Task 1 Output**: Showing the result of adding two integers.
+2. **Task 2 Output**: Demonstrating user input validation and array summation.
+3. **Task 3 Build**: Displaying the successful build process using the `Makefile`.
+
+Include brief explanations for each screenshot.
+
+---
## Authors
- Hazal Veziroglu
+---
+
## License
This project is licensed under the MIT License. See the `LICENSE` file for details.
+---
+
## Acknowledgments
-- UWE Course Material on Assembly Programming
+- UWE Course Material on Assembly Programming.
- Online assembly programming resources and communities.
--
GitLab